aicyclingcoach-go/export_import_api_spec.md

Export/Import API Specification

Export Endpoint

GET /api/export

Parameters (query string)

• types (required): Comma-separated list of data types to export
  • Valid values: routes, rules, plans, all
• format (required): Export format
  • json: Single JSON file
  • zip: ZIP archive with separate files
  • gpx: Only GPX files (routes only)

Response

• 200 OK with file download
• 400 Bad Request for invalid parameters
• 500 Internal Server Error for export failures

Example

GET /api/export?types=routes,plans&format=zip

---

Import Validation

POST /api/import/validate

Request

• Multipart form with file field containing import data

Response

{
  "valid": true,
  "conflicts": [
    {
      "type": "route",
      "id": 123,
      "name": "Mountain Loop",
      "existing_version": 2,
      "import_version": 3,
      "resolution_options": ["overwrite", "rename", "skip"]
    }
  ],
  "summary": {
    "routes": 15,
    "rules": 3,
    "plans": 2
  }
}

---

Import Execution

POST /api/import

Request

• Multipart form with:
  • file: Import data file
  • conflict_resolution: Global strategy (overwrite, skip, rename)
  • resolutions: JSON array of specific resolutions (optional)

    [{"type": "route", "id": 123, "action": "overwrite"}]
    

Response

{
  "imported": {
    "routes": 12,
    "rules": 3,
    "plans": 2
  },
  "skipped": {
    "routes": 3,
    "rules": 0,
    "plans": 0
  },
  "errors": []
}

Status Codes

• 200 OK: Import completed
• 202 Accepted: Import in progress (async)
• 400 Bad Request: Invalid input
• 409 Conflict: Unresolved conflicts

---