Third-party sync API (Eve Period Tracker)

Base URL Configuration

The app supports flexible base URL configurations:

  • Recommended: https://api.example.com/v1/cloudkit (full path)
  • Also supported: https://api.example.com (the app auto-appends /v1/cloudkit/{action})
  • Legacy compatible: Paths with /v1/Cloudkit/ or /api/v1/cloudkit/

The app automatically normalizes URLs and retries common path variants on HTTP 404.

Authentication

If the user enters an API Key in the app, it is sent as:

X-API-Key: {apiKey}

If left blank, no Authorization header is added.

Upload Endpoint

POST {base}/save

Example: POST https://api.example.com/v1/cloudkit/save

Request Body:

{
  "user_id": "string",              // required, user identifier
  "app_name": "Eve Period",         // fixed app name
  "name": "period-backup",          // fixed backup name
  "remark": "iOS backup from Eve Period",
  "sync_type": "upload",            // indicates upload intent
  "data": [                         // array of period entries
    {
      "id": "UUID",                 // unique entry ID
      "startDate": "2024-01-01T00:00:00Z",  // ISO 8601 format
      "note": "",                   // optional note
      "isPredicted": false,         // prediction flag
      "sequence": 1,                // entry sequence
      "type": "come",               // entry type
      "cycleLength": 28             // cycle length in days
    }
  ]
}

Success Response (200):

{
  "code": 0,
  "message": "ok",
  "data": {}
}

Error Response (4xx/5xx):

{
  "code": 1,
  "message": "Error description"
}

Or FastAPI style:

{
  "detail": "Error description"
}

Download Endpoint

GET {base}/show

Example: GET https://api.example.com/v1/cloudkit/show?user_id=xxx&app_name=Eve%20Period&sync_type=download

Query Parameters:

  • user_id (required): User identifier
  • app_name (required): Eve Period
  • sync_type (required): download

Success Response (200):

{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "id": "UUID",
      "startDate": "2024-01-01T00:00:00Z",
      "note": "",
      "isPredicted": false,
      "sequence": 1,
      "type": "come",
      "cycleLength": 28
    }
  ]
}

The response data should be an array of entries matching the upload format. The app merges/overwrites local data based on the selected sync mode.

Error Handling

The app displays detailed error messages including:

  • HTTP status code (e.g., 401, 404, 500)
  • Request URL
  • Server error message from message or detail field

Example error shown to user:

API failed (HTTP 404) at https://api.example.com/v1/cloudkit/save: Not Found

Path Auto-Correction

On HTTP 404, the app automatically retries with common path variants:

  • Case variations: /v1/cloudkit/ ↔ /v1/Cloudkit/
  • Prefix removal: /api/v1/cloudkit/ → /v1/cloudkit/
  • Path reconstruction from configured base URL

This ensures compatibility with various server configurations without manual adjustment.