API Reference

This document provides comprehensive information about the SparkyFitness API, including OpenAPI specification, endpoints, and integration guidelines.

OpenAPI Specification

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs. It allows both humans and computers to discover and understand the capabilities of a service without access to source code, documentation, or network traffic inspection.

Purpose in SparkyFitness

For SparkyFitness, an OpenAPI specification would serve several key purposes:

  • API Documentation: Provides clear and interactive documentation for all backend API endpoints, including request parameters, response structures, and authentication methods.
  • Client Code Generation: Enables automatic generation of client SDKs (Software Development Kits) in various programming languages, simplifying integration for third-party applications or mobile clients.
  • API Testing: Facilitates automated testing of API endpoints, ensuring consistency and correctness.
  • Design and Collaboration: Serves as a single source of truth for API design, improving collaboration between frontend and backend developers.

Key Elements of SparkyFitness's API (as described by OpenAPI)

An OpenAPI specification for SparkyFitness would detail:

  • Endpoints: All available API routes (e.g., /api/food, /api/users, /api/exercises).
  • Operations: HTTP methods supported for each endpoint (GET, POST, PUT, DELETE).
  • Parameters: Input parameters for each operation, including their types, formats, and whether they are required.
  • Responses: The structure of successful and error responses, including status codes and data models.
  • Authentication: How clients authenticate with the API (e.g., JWT tokens).
  • Data Models (Schemas): Definitions of the data structures used in requests and responses (e.g., FoodItem, UserProfile, ExerciseEntry).

Accessing the API Documentation

While a live, interactive OpenAPI documentation (like Swagger UI) might be available in development environments, the core API is consumed by the SparkyFitness frontend and can be explored by examining the backend routes in SparkyFitnessServer/routes/ and the service definitions in SparkyFitnessServer/services/.

Detailed API Endpoints

Authentication

  • API Key: Used for specific endpoints like /api/health-data. The API Key should be sent in the Authorization header as Bearer <API_KEY> or in the X-API-Key header. The API Key must have the necessary permissions (e.g., health_data_write).
  • JWT Token: Used for most authenticated endpoints. The JWT token should be sent in the Authorization header as Bearer <JWT_TOKEN>.

Error Handling

General error responses follow a consistent structure:

  • 400 Bad Request: Indicates invalid input or missing required fields.
  • 401 Unauthorized: Occurs when authentication credentials are missing or invalid.
  • 403 Forbidden: Occurs when the authenticated user does not have the necessary permissions.
  • 404 Not Found: The requested resource could not be found.
  • 500 Internal Server Error: An unexpected error occurred on the server.

Example Error Response:

{
  "error": "Error message describing the issue."
}

Endpoints

1. /api/health-data

  • Path: /api/health-data
  • Method: POST
  • Description: Submits various health data points (e.g., weight, steps, active calories, custom measurements) to the system. This endpoint is crucial for integrating SparkyFitness with external health tracking services like iOS Shortcuts and Android mobile apps, allowing seamless data submission.
  • Authentication: API Key (sent via Authorization header as Bearer <API_KEY> or X-API-Key header). The API Key must have health_data_write permission.
  • Request Body: An array of health data objects, or a single health data object.
    • Structure: 
      [
  {
    "value": <number>,
    "type": "<string>",
    "date": "<YYYY-MM-DD>",
    "timestamp": "<ISO 8601 string, optional>"
  },
  ...
]
    • Fields:
      • value (required, number): The measurement value.
      • type (required, string): The type of health data. This field is case-sensitive. Supported types include:
        • weight: Records body weight.
        • step: Records the number of steps taken.
        • water: Records water intake in milliliters.
        • Active Calories: Records calories burned through physical activity.
        • Any other string: Will be treated as a custom measurement category. If a category with this name does not exist, it will be automatically created.
      • date (required, string): The date of the measurement in YYYY-MM-DD format (e.g., "2025-08-19").
      • timestamp (optional, string): The exact timestamp of the measurement in ISO 8601 format (e.g., "2025-08-19T08:30:00Z"). If provided, the entryHour will be extracted for more granular tracking.
    • Examples:
      • Weight: 
        [
  {
    "value": 70.5,
    "type": "weight",
    "date": "2025-08-19"
  }
]
      • Steps: 
        [
  {
    "value": 10000,
    "type": "step",
    "date": "2025-08-19"
  }
]
      • Water Intake: 
        [
  {
    "value": 500,
    "type": "water",
    "date": "2025-08-19"
  }
]
      • Active Calories: 
        [
  {
    "value": 500,
    "type": "Active Calories",
    "date": "2025-08-19"
  }
]
      • Custom Measurement (e.g., "Blood Pressure Systolic"): 
        [
  {
    "value": 120,
    "type": "Blood Pressure Systolic",
    "date": "2025-08-19",
    "timestamp": "2025-08-19T08:30:00Z"
  }
]
  • Responses:
    • 200 OK: 
      {
  "message": "All health data successfully processed.",
  "processed": [
    {
      "type": "weight",
      "status": "success",
      "data": { "id": "uuid", "user_id": "uuid", "entry_date": "2025-08-19", "weight": 70.5 }
    }
  ]
}
    • 400 Bad Request: 
      {
  "error": "Invalid JSON array format."
}
      or 
      {
  "message": "Some health data entries could not be processed.",
  "processed": [],
  "errors": [
    {
      "error": "Missing required fields: value, type, date in one of the entries",
      "entry": { "value": null, "type": "weight", "date": "2025-08-19" }
    }
  ]
}
    • 401 Unauthorized: 
      {
  "error": "Unauthorized: Missing API Key"
}
      or 
      {
  "error": "Unauthorized: Invalid or inactive API Key"
}
    • 403 Forbidden: 
      {
  "error": "Forbidden: API Key does not have health_data_write permission"
}

2. /api/measurements/check-in

  • Path: /api/measurements/check-in
  • Method: POST
  • Description: Upserts (inserts or updates) daily check-in measurements for the authenticated user. Only one check-in entry is allowed per day.
  • Authentication: JWT Token (sent via Authorization header as Bearer <JWT_TOKEN>).
  • Request Body:
    • Structure: 
      {
  "entry_date": "<YYYY-MM-DD>",
  "weight": <number, optional>,
  "body_fat": <number, optional>,
  "bmi": <number, optional>,
  "neck": <number, optional>,
  "chest": <number, optional>,
  "waist": <number, optional>,
  "hips": <number, optional>,
  "thigh": <number, optional>,
  "calf": <number, optional>,
  "bicep": <number, optional>,
  "forearm": <number, optional>,
  "steps": <number, optional>
}
    • Fields:
      • entry_date (required, string): The date of the check-in in YYYY-MM-DD format.
      • Other fields (optional, number): Various measurement values.
  • Responses:
    • 200 OK: 
      {
  "message": "Check-in measurements upserted successfully.",
  "data": { "id": "uuid", "user_id": "uuid", "entry_date": "2025-08-19", "weight": 70.5 }
}
    • 400 Bad Request: 
      {
  "error": "Entry date is required."
}
    • 401 Unauthorized: (If JWT is missing or invalid)
    • 403 Forbidden: (If user is not authorized)
  • Path: /api/measurements/check-in/:date
  • Method: GET
  • Description: Retrieves daily check-in measurements for a specific date for the authenticated user.
  • Authentication: JWT Token.
  • Path Parameters:
    • date (required, string): The date of the check-in in YYYY-MM-DD format.
  • Responses:
    • 200 OK: 
      {
  "id": "uuid",
  "user_id": "uuid",
  "entry_date": "2025-08-19",
  "weight": 70.5,
  "body_fat": 15.2
}
      or {} if no entry found for the date.
    • 400 Bad Request: 
      {
  "error": "Date is required."
}
    • 401 Unauthorized:
    • 403 Forbidden:
  • Path: /api/measurements/check-in/:entry_date
  • Method: PUT
  • Description: Updates an existing daily check-in measurement entry for a specific date.
  • Authentication: JWT Token.
  • Path Parameters:
    • entry_date (required, string): The date of the check-in in YYYY-MM-DD format.
  • Request Body:
    • Structure: Same as POST request for /api/measurements/check-in, but entry_date is provided in the path.
    • Fields: Any of the optional measurement fields (e.g., weight, body_fat, neck, etc.) to update.
  • Responses:
    • 200 OK: 
      {
  "id": "uuid",
  "user_id": "uuid",
  "entry_date": "2025-08-19",
  "weight": 71.0,
  "body_fat": 15.2
}
    • 400 Bad Request: 
      {
  "error": "Entry date is required."
}
    • 401 Unauthorized: (If JWT is missing or invalid)
    • 403 Forbidden: (If user is not authorized)
    • 404 Not Found: 
      {
  "error": "Check-in measurement not found or not authorized to update."
}
  • Path: /api/measurements/check-in/:id
  • Method: DELETE
  • Description: Deletes a daily check-in measurement entry.
  • Authentication: JWT Token.
  • Path Parameters:
    • id (required, string): The ID of the check-in entry to delete.
  • Responses:
    • 200 OK: 
      {
  "message": "Check-in measurement deleted successfully."
}
    • 400 Bad Request: 
      {
  "error": "Check-in Measurement ID is required."
}
    • 401 Unauthorized:
    • 403 Forbidden:
    • 404 Not Found: 
      {
  "error": "Check-in measurement not found or not authorized to delete."
}
Table of Contents