FitTrack_GarminSync/specs/004-home-sstent-projects/contracts/garmin_sync_status.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Garmin Sync API with Progress Tracking",
    "version": "1.0.0",
    "description": "API for initiating and tracking the status of Garmin data synchronization for a single user."
  },
  "servers": [
    {
      "url": "/api/v1"
    }
  ],
  "paths": {
    "/garmin/activities": {
      "post": {
        "summary": "Initiate Garmin Activity Synchronization",
        "operationId": "syncGarminActivities",
        "tags": ["Garmin Sync"],
        "responses": {
          "200": {
            "description": "Activity synchronization initiated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Activity synchronization initiated successfully."
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict: A sync is already in progress.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string",
                      "example": "A synchronization is already in progress. Please wait or check status."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/garmin/workouts": {
      "post": {
        "summary": "Initiate Garmin Workout Synchronization",
        "operationId": "syncGarminWorkouts",
        "tags": ["Garmin Sync"],
        "responses": {
          "200": {
            "description": "Workout synchronization initiated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Workout synchronization initiated successfully."
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict: A sync is already in progress.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string",
                      "example": "A synchronization is already in progress. Please wait or check status."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/garmin/health": {
      "post": {
        "summary": "Initiate Garmin Health Metrics Synchronization",
        "operationId": "syncGarminHealth",
        "tags": ["Garmin Sync"],
        "responses": {
          "200": {
            "description": "Health metrics synchronization initiated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Health metrics synchronization initiated successfully."
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict: A sync is already in progress.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string",
                      "example": "A synchronization is already in progress. Please wait or check status."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/garmin/sync/status": {
      "get": {
        "summary": "Get Current Garmin Sync Status",
        "operationId": "getGarminSyncStatus",
        "tags": ["Garmin Sync"],
        "responses": {
          "200": {
            "description": "Current status of the Garmin synchronization job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SyncJob"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SyncJob": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "Current state of the sync.",
            "enum": ["idle", "in_progress", "completed", "failed"],
            "example": "in_progress"
          },
          "progress": {
            "type": "number",
            "format": "float",
            "description": "Completion percentage (0.0 to 1.0).",
            "minimum": 0.0,
            "maximum": 1.0,
            "example": 0.5
          },
          "start_time": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the sync operation began.",
            "example": "2025-10-11T10:00:00Z"
          },
          "end_time": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp when the sync operation concluded (either completed or failed).",
            "example": "2025-10-11T10:15:00Z"
          },
          "error_message": {
            "type": "string",
            "nullable": true,
            "description": "Details if the sync operation failed.",
            "example": "Failed to connect to Garmin API."
          },
          "job_type": {
            "type": "string",
            "nullable": true,
            "description": "Type of data being synchronized.",
            "enum": ["activities", "health", "workouts"],
            "example": "activities"
          }
        },
        "required": ["status", "progress", "start_time"]
      }
    }
  }
}