FitTrack_GarminSync/specs/003-loginimprovements-use-the/quickstart.md

Quickstart: Garmin Login Improvements

This guide provides a quick way to test the Garmin login and initial synchronization feature.

Prerequisites

• A running instance of the FitTrack Garmin Sync backend.
• curl installed on your system.

1. Link your Garmin Account

Send a POST request to the /api/garmin/login endpoint with your Garmin Connect username (email) and password. This will link your Garmin account with the service and store your credentials for automatic token management.

Endpoint: POST /api/garmin/login

Example using curl:

API_BASE_URL="http://localhost:8000" # Adjust if your API is running on a different host/port
GARMIN_USERNAME="your_garmin_email@example.com" # Replace with your Garmin email
GARMIN_PASSWORD="your_garmin_password" # Replace with your Garmin password

curl -s -X POST "${API_BASE_URL}/api/garmin/login" \
  -H "Content-Type: application/json" \
  -d "{
        \"username\": \"${GARMIN_USERNAME}\",
        \"password\": \"${GARMIN_PASSWORD}\" 
      }"

Expected Success Response (200 OK):

{
  "message": "Garmin account linked successfully."
}

2. Initiate Garmin Activity Synchronization

Once your Garmin account is linked, you can trigger an activity synchronization. The backend will implicitly use the stored Garmin credentials. No additional authentication headers are required from the client for this operation.

Endpoint: POST /api/sync/garmin/activities

Example using curl:

API_BASE_URL="http://localhost:8000" # Adjust if your API is running on a different host/port

curl -s -X POST "${API_BASE_URL}/api/sync/garmin/activities" \
  -H "Content-Type: application/json" \
  -d "{}"

Expected Success Response (202 Accepted):

{
  "message": "Garmin activity synchronization initiated.",
  "sync_job_id": "a-uuid-representing-the-sync-job"
}

3. Check Synchronization Status

After initiating a synchronization job, you can check its status using the /api/sync/status endpoint. You will need the job_id returned from the synchronization initiation step.

Endpoint: GET /api/sync/status

Example using curl:

API_BASE_URL="http://localhost:8000" # Adjust if your API is running on a different host/port
JOB_ID="<PASTE_YOUR_JOB_ID_HERE>" # Replace with the job_id from Step 2

curl -s -X GET "${API_BASE_URL}/api/sync/status?job_id=${JOB_ID}"

Expected Response (200 OK):

[
  {
    "id": "a-uuid-representing-the-sync-job",
    "status": "completed", // or "pending", "in_progress", "failed"
    "start_time": "2025-10-11T00:00:00.000000",
    "end_time": "2025-10-11T00:01:00.000000",
    "progress": 1.0,
    "error_message": null,
    "details": {
      "synced_activities_count": 5,
      "total_activities_found": 5
    }
  }
]