API Documentation Template

Auteur
Affiliations

Emmanuel BRUNO

Université de Toulon

LIS UMR CNRS 7020

Date de publication

2026-10-03

API Documentation Template

NoteTemplate Usage
  1. Replace [API_NAME] with your API name
  2. Define authentication method
  3. Document endpoints and data structures
  4. Add specific error codes and responses

API Overview

[API_NAME] exposes RESTful APIs for [PURPOSE].

Base URL: [BASE_URL]

Authentication

[Define authentication method]

Authentication Flow

sequenceDiagram
    participant Client
    participant Auth
    participant API
    
    Client->>Auth: Authentication Request
    Auth-->>Client: Auth Token
    Client->>API: API Request + Token
    API-->>Client: Response

API Versioning

The API uses URL-based versioning (/v1, /v2) for major changes and header-based versioning for minor changes.

For minor version selection, include:

API-Version: [VERSION]

Common Response Format

All API responses follow this JSON structure:

{
  "status": "success|error",
  "data": {
    // Response data object(s)
  },
  "message": "Human readable message (mainly for errors)",
  "code": 200, // HTTP status code
  "timestamp": 1652345678910
}

Error Handling

Error Codes

Status Code Description
400 Bad Request - Invalid input parameters
401 Unauthorized - Authentication required
403 Forbidden - Insufficient permissions
404 Not Found - Resource doesn’t exist
409 Conflict - Resource state conflict
422 Unprocessable Entity - Validation error
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server-side issue
503 Service Unavailable - Temporary outage

Error Response Example

{
  "status": "error",
  "message": "Validation failed",
  "code": 422,
  "timestamp": 1652345678910,
  "errors": [
    {
      "field": "weight",
      "message": "Weight must be a positive number"
    },
    {
      "field": "reps",
      "message": "Reps must be between 1 and 100"
    }
  ]
}

Resource Endpoints

User Endpoints

Get User Profile

GET /users/profile

Response:

{
  "status": "success",
  "data": {
    "userId": "user123",
    "displayName": "John Doe",
    "email": "john@example.com",
    "profileImageUrl": "https://cdn.fitnesstracker.com/profiles/user123.jpg",
    "dateJoined": 1641034800000,
    "fitnessLevel": "INTERMEDIATE",
    "heightCm": 180,
    "weightKg": 75,
    "dateOfBirth": 599634000000,
    "gender": "MALE",
    "isPremium": true,
    "settings": {
      "useMetricSystem": true,
      "enableNotifications": true,
      "darkModePreference": "SYSTEM",
      "restTimerDuration": 60
    }
  },
  "code": 200,
  "timestamp": 1652345678910
}

Update User Profile

PUT /users/profile

Request Body:

{
  "displayName": "John Doe",
  "heightCm": 180,
  "weightKg": 75,
  "fitnessLevel": "INTERMEDIATE",
  "gender": "MALE"
}

Response:

{
  "status": "success",
  "data": {
    "userId": "user123",
    "displayName": "John Doe",
    // ...updated user data
  },
  "message": "Profile updated successfully",
  "code": 200,
  "timestamp": 1652345678910
}

Template Validation

Réutilisation