Endpoints

Cette page est l'index des routes : de quoi trouver la bonne en un coup d'œil. Le détail de chacune (corps attendu, réponses, exemples, et un formulaire pour l'essayer) est dans Swagger :

Environnement	Swagger	Description OpenAPI (JSON)
Local	http://localhost:4000/api/docs	/api/openapi
Production	api.time.jostud.com/api/docs	/api/openapi

Essayer une route protégée dans Swagger

POST /api/auth/login avec "client": "mobile", puis le bouton Authorize, et colle l'access_token. Les routes avec un cadenas sont alors utilisables.

Légende : E employé, M manager, GM General Manager. « Soi » = sur son propre compte, « ses gens » = les membres de ses équipes (voir Droits par rôle).

Sessions et liens envoyés par e-mail

Publiques : personne n'a besoin d'être connecté.

Méthode	Route	Rôle
POST	/api/auth/login	se connecter ("client": "mobile" pour recevoir les jetons)
POST	/api/auth/refresh	obtenir de nouveaux jetons
POST	/api/auth/logout	se déconnecter
GET	/api/auth/me	la personne connectée (connecté)
POST	/api/auth/forgot-password	envoyer un lien de réinitialisation (toujours 204)
GET	/api/password-tokens/:token	ce lien est-il encore valable, et pour qui ?
POST	/api/password-tokens/:token	choisir son mot de passe (réinitialisation ou invitation)
POST	/api/email-change/:token	confirmer une nouvelle adresse e-mail

Comptes

Méthode	Route	Qui
GET	/api/users	M (comptes actifs), GM (tous)
POST	/api/users	GM : inviter une personne
GET	/api/users/:id	soi, ses gens (M), tous (GM)
PUT, PATCH	/api/users/:id	soi : changer son nom
DELETE	/api/users/:id	soi (sauf le GM), les autres (GM)
PUT	/api/users/:id/role	GM : promouvoir ou retirer les droits (jamais soi)
POST	/api/users/:id/invitation	GM : renvoyer l'invitation
PUT	/api/users/:id/password	soi : changer de mot de passe
PUT	/api/users/:id/preferences	soi : langue et thème
POST, GET	/api/users/:id/email-change	GM, soi : demander à changer d'e-mail, voir la demande en attente
GET	/api/users/:id/data	soi : tout ce que l'API garde sur soi

Pointage

Méthode	Route	Qui
GET	/api/clocks/:userID	soi, ses gens (M), tous (GM)
POST	/api/clocks/:userID	soi : arrivée ou départ
POST	/api/clocks/:userID/break	soi : début ou fin de pause

Journées de travail

Les routes imposées par le sujet, où :userID désigne la personne et :id la journée.

Méthode	Route	Qui
GET	/api/workingtime/:userID	soi, ses gens (M), tous (GM) ; ?start=…&end=… facultatifs
GET	/api/workingtime/:userID/:id	les mêmes
POST	/api/workingtime/:userID	ses gens (M), tous (GM), jamais soi
PUT	/api/workingtime/:id	les mêmes
DELETE	/api/workingtime/:id	les mêmes
GET	/api/users/:id/changes	le journal des modifications : soi, ses gens (M), tous (GM)

Absences et semaines

Méthode	Route	Qui
GET	/api/users/:id/absences	soi, ses gens (M), tous (GM)
POST	/api/users/:id/absences	ses gens (M), tous (GM), jamais soi
DELETE	/api/absences/:id	les mêmes
GET	/api/users/:id/week-validations	soi, ses gens (M), tous (GM)
POST	/api/users/:id/week-validations	ses gens (M), tous (GM), jamais soi
PUT	/api/week-validations/:id/reopen	le manager qui l'a validée, le GM

Demandes de correction

Méthode	Route	Qui
GET	/api/corrections	les siennes, plus celles qu'on peut examiner
POST	/api/corrections	tous, pour leurs propres heures
PUT	/api/corrections/:id/approve	ses gens (M), toutes (GM, la sienne comprise)
PUT	/api/corrections/:id/reject	les mêmes

Équipes et moyennes

Méthode	Route	Qui
GET	/api/teams	les siennes (M), toutes (GM)
POST	/api/teams	M (dont il est le manager), GM
GET, PUT, PATCH, DELETE	/api/teams/:id	son manager, le GM (changer de manager : GM seulement)
POST	/api/teams/:id/members	son manager, le GM
DELETE	/api/teams/:id/members/:user_id	son manager, le GM
GET	/api/teams/:id/averages	son manager, le GM ; ?start=…&end=… obligatoires
GET	/api/users/:id/averages	soi, ses gens (M), tous (GM) ; ?start=…&end=… obligatoires

Notifications

Méthode	Route	Qui
GET	/api/notifications	les siennes (les 30 plus récentes)
PUT	/api/notifications/read	marquer les siennes comme lues

Documentation

Méthode	Route	Rôle
GET	/api/docs	Swagger UI
GET	/api/openapi	la description OpenAPI, en JSON

Une nouvelle route se documente

Le test api_docs_test.exs vérifie que chaque route du routeur est décrite dans Swagger, et que les vraies réponses respectent leurs schémas. Une route ajoutée sans sa description fait échouer les tests (voir Ajouter une route).