Contrat et référence API

La référence API interactive est rendue par Scalar à partir de backend/docs/openapi.yaml. Ce fichier OpenAPI 3.1 est la source de vérité des endpoints custom ; les handlers, DTO, repositories frontend et collections Postman doivent rester alignés.

Lire le contrat

Chaque opération documente au minimum :

• méthode et chemin ;
• résumé et identifiant d’opération stables ;
• authentification et rôles lorsque nécessaire ;
• paramètres de chemin et de requête ;
• corps, champs requis, formats et limites ;
• réponse nominale avec exemple ;
• erreurs attendues et leur schéma.

La référence Scalar permet d’explorer les schémas et de préparer une requête. N’y saisissez pas un token de production sur un environnement non approuvé.

Conventions de l’API

Ressources et identifiants

Les collections utilisent des noms pluriels. Les pages publiques préfèrent un slug stable dans l’URL ; les opérations administratives peuvent utiliser un identifiant opaque lorsque le contrat le prévoit. Encodez toujours un segment provenant de l’utilisateur.

Localisation

Les endpoints traduisibles acceptent ?locale=xx. Le backend valide la locale, renvoie sa traduction ou applique le fallback documenté. Le frontend ne fabrique pas une traduction manquante.

Pagination et filtres

Les listes bornent page et page_size. Les filtres ont une liste de valeurs documentée. Ajoutez un exemple combinant pagination et filtre afin que le consommateur voie la forme de réponse complète.

Dates et nombres

• dates et instants : ISO 8601 ;
• montants : unité et devise explicites dans le schéma ;
• durées : nom d’unité non ambigu ou format documenté ;
• champs optionnels : différence claire entre absence, null et valeur vide.

Erreurs

Une erreur publique reste stable et exploitable sans exposer de stack trace, requête SQL, URL privée ou message fournisseur. Documentez le statut et le corps que le frontend peut réellement traiter.

Authentification

Les endpoints back-office utilisent un bearer token obtenu après mot de passe et TOTP. OpenAPI doit déclarer le schéma de sécurité sur chaque opération protégée et préciser les restrictions de rôle.

Le navigateur ne manipule pas ce bearer token. SvelteKit le conserve dans un cookie httpOnly et l’ajoute uniquement aux appels serveur vers le backend.

Faire évoluer un endpoint

1. Écrivez ou ajustez la règle de domaine et ses tests.
2. Modifiez le handler et les DTO.
3. Mettez à jour le chemin, les schémas, exemples et erreurs dans docs/openapi.yaml.
4. Ajoutez un test d’intégration de la réponse réelle.
5. Exécutez make contract puis make verify dans backend/.
6. Mettez à jour les types et mappings dans web/src/lib/infrastructure.
7. Gérez les états loading, vide, erreur et conflit dans le frontend.
8. Exécutez les validations web et les E2E cross-stack.

Compatibilité

Classez le changement avant de coder :

Changement	Compatibilité habituelle	Stratégie
Nouveau champ optionnel	additive	backend puis frontend
Nouvel endpoint	additive	backend puis consommateur
Champ désormais requis en entrée	cassante	accepter ancien et nouveau pendant la transition
Renommage ou suppression	cassante	dupliquer, migrer, retirer plus tard
Nouveau membre d’un enum	potentiellement cassante	prévoir un fallback côté consommateur
Sens modifié sans schéma modifié	cassante et difficile à détecter	nouvelle version ou nouveau champ

Ne supposez pas que les deux applications seront redéployées au même instant.

Synchronisation dans le portail

Le script documentation/scripts/sync-openapi.mjs essaie dans l’ordre :

1. ${HARMONY_BACKEND_DIR}/docs/openapi.yaml ;
2. le dépôt frère backend/docs/openapi.yaml ;
3. l’instantané versionné documentation/openapi.yaml lorsqu’aucune URL n’est configurée ;
4. HARMONY_BACKEND_OPENAPI_URL si aucune source locale n’est disponible.

Pour une branche backend locale :

HARMONY_BACKEND_DIR=../backend npm run docs:dev

documentation/public/openapi.yaml est généré et ignoré par Git. Ne le modifiez pas.

Lot cross-stack

Lorsque le dépôt backend est privé, la CI web ne peut pas le cloner sans secret. Une PR web coordonnée recopie donc le contrat validé vers web/documentation/openapi.yaml. Vérifiez que cet instantané provient exactement de la branche backend associée.

Vérification

# backend
make contract

# portail web avec contrat local
HARMONY_BACKEND_DIR=../backend npm run docs:check
HARMONY_BACKEND_DIR=../backend npm run docs:build

Le test de contrat vérifie les opérations obligatoires et la structure exécutable du document. Il ne remplace pas un test d’intégration qui compare le comportement du handler.

Postman

backend/postman/harmony-api.postman_collection.json offre une collection manuelle avec baseUrl, locale et authToken. Mettez-la à jour lorsqu’un parcours de diagnostic utile n’est plus conforme, mais ne considérez pas Postman comme la source du contrat.