Référence de l'API

URL de base et format des réponses

Chaque route est servie sous le préfixe /api. En local, l'URL de base est http://localhost:8000/api. Sur un serveur, c'est l'adresse de votre API suivie de /api, la même valeur que le tableau de bord lit dans NEXT_PUBLIC_API_BASE_URL (Variables d'environnement).

Les membres et l'équipe utilisent la même connexion et le même jeton ; les rôles du compte décident des routes qui répondent. Les corps de requête sont en JSON, sauf pour les envois de fichiers. Chaque réponse arrive dans la même enveloppe :

{
  "success": true,
  "data": { },
  "message": ""
}

data contient le résultat. message est une courte phrase que certaines écritures renseignent, traduite dans la langue de la requête, et vide sinon.

La vérification de santé est la seule route en dehors de l'enveloppe. Elle ne demande aucun jeton et n'est pas soumise à une limite de requêtes :

curl http://localhost:8000/api/health

{"status":"ok"}

Elle répond 503 avec {"status":"unavailable"} tant que la base de données est injoignable ou ne contient aucune table : une plateforme peut donc l'utiliser comme sonde de disponibilité.

Erreurs

Une requête échouée répond avec le statut HTTP correspondant et la même enveloppe, avec success: false, data: null et, pour la validation, les problèmes par champ :

{
  "success": false,
  "data": null,
  "message": "<the first field's problem>",
  "errors": {
    "email": ["<the problem with email>"]
  }
}

De nombreuses erreurs portent dans message une clé que le tableau de bord traduit, par exemple member_not_found ou event_full.

Pagination

Les listes acceptent page, à partir de 1, et page_count, la taille de page. Une page contient au plus 100 lignes : une taille plus grande est lue comme 100, une plus petite comme 1, et une taille absente ou illisible revient à la valeur par défaut de la liste. Une liste répond toujours sous la même forme :

{
  "success": true,
  "data": { "data": [ ], "page": 1, "limit": 15, "total": 35, "totalPages": 3 },
  "message": ""
}

Les listes de contenu sont triées par updated_at, les plus récentes en premier par défaut (order=asc ou desc), avec l'identifiant pour départager, et acceptent search et leurs propres filtres.

Langue

Envoyez la langue du lecteur dans l'en-tête Accept-Language : en ou ar à la livraison. ar-SA compte comme de l'arabe, et toute langue que l'API ne possède pas reçoit une réponse en anglais. Les messages d'erreur et le message d'une écriture réussie sont traduits ; le contenu enregistré dans les deux langues revient sous la forme { "en": "...", "ar": "..." }.

Authentification

• Connectez-vous via POST /api/auth/login. La réponse contient access_token, un JWT signé avec JWT_SECRET, et le compte avec ses rôles et ses permissions. Envoyez-le sous la forme Authorization: Bearer <token>.
• Un jeton dure JWT_EXPIRATION, 7d par défaut. Il n'y a pas de route de rafraîchissement : quand un jeton expire, la requête suivante répond 401 et le client se reconnecte.
• La connexion, l'inscription et la suppression de compte acceptent 10 tentatives par minute depuis une même adresse, comptées par route, puis répondent 429. Le compteur est gardé en mémoire par l'API : il repart donc de zéro à un redémarrage. Derrière un proxy, voir TRUST_PROXY (Dépannage).

1. 01

   Se connecter en tant que Head Coach du seed

   TerminalCopier

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"headcoach@example.com","password":"Coach@123"}'

   RéponseCopier

   {
     "success": true,
     "data": {
       "access_token": "eyJhbGciOiJIUzI1NiIs...",
       "token_type": "Bearer",
       "expires_in": "7d",
       "account": { "email": "headcoach@example.com", "roles": [ ], "permissions": [ ] }
     },
     "message": "..."
   }
2. 02

   Appeler une route protégée avec le jeton

   TerminalCopier

   curl "http://localhost:8000/api/users?page=1&page_count=5" \
     -H "Authorization: Bearer <access_token>"

   Résultat attendu: Les cinq premiers membres, au format de liste.

Il n'existe aucune route de réinitialisation du mot de passe. Les pages de mot de passe oublié et de réinitialisation du tableau de bord ne sont que des écrans : aucune réinitialisation n'est envoyée. Un compte de l'équipe avec members.update définit le mot de passe d'un membre avec PATCH /api/users/:username/change-password.

Permissions

Une route vérifie d'abord le jeton, puis la permission qu'elle nomme. Un compte détient toutes les permissions de tous ses rôles ; quand une route en nomme plusieurs, une seule suffit. Dans les tableaux ci-dessous, un nom de permission dans Qui peut l'appeler désigne un compte dont les rôles l'accordent.

• Les rôles et leurs permissions

Les membres

Coachs et rôles

Réglages de l'application

Les propres données d'un membre

Chaque route ici répond pour le compte du jeton et personne d'autre. Un jeton de l'équipe répond 403, car seul le rôle Member détient fitness.view et fitness.edit. Chaque écriture répond avec toute la page actualisée.

• Progrès et saisie
• Appareils et clés d'ingestion

Séances d'entraînement, exercices et séance

Coaching

Les routes de liste de clients répondent pour le coach qui fait la requête : le client d'un autre coach renvoie 404.

Les catalogues de contenu

Chaque catalogue répond aux cinq mêmes routes sous /api/fitness/manage/<catalogue>, et chacune demande fitness.manage. Les catalogues sont exercises, workouts, programs, dishes, groups, events, challenges, achievements et badges.

Un identifiant inconnu renvoie 404 record_not_found. Les noms et les textes sont envoyés sous la forme { "en": "…", "ar": "…" } ; les calories d'un plat ne sont jamais envoyées, elles sont calculées à partir de ses grammes.

Ingestion

La porte d'entrée des appareils et des agrégateurs. Ces routes prennent une clé d'ingestion dans X-Api-Key, jamais un jeton bearer, et n'écrivent que pour le compte de la clé.

• Appareils et clés d'ingestion

Recherche, envois de fichiers, notifications et pays

Deux namespaces Socket.IO sur le même serveur envoient des mises à jour en direct : /notifications transmet chaque nouvelle notification, et /auth signale à un tableau de bord connecté que ses permissions ont changé. Ils acceptent les origines de FRONTEND_URL, ou de CORS_ORIGIN quand il n'est pas défini.

• Comment la recherche classe ses résultats

Assistant IA

Serveur MCP

Routes du mode démo