Conventions REST, erreurs et multi-tenant

Les API de tous les modules partagent les mêmes conventions.

Format¶

• JSON en entrée et en sortie ; Content-Type: application/json.
• Les identifiants de ressources sont des GUID ({id:guid}).
• Les dates sont en ISO 8601 UTC (ex. 2026-07-08T11:48:43Z).

Verbes et statuts¶

Verbe	Usage	Succès
GET	Lecture	200
POST	Création / action	200 ou 201
PATCH	Mise à jour partielle	200
PUT	Remplacement / upsert	200
DELETE	Suppression / archivage	200 ou 204

Erreurs¶

Les erreurs renvoient un corps JSON lisible :

{ "error": "Cette clé est en lecture seule (scope read)." }

Code	Signification
400	Requête invalide (validation)
401	Non authentifié (jeton absent, expiré ou révoqué)
403	Interdit — module non inclus dans l'abonnement (gating) ou scope insuffisant
404	Ressource introuvable ou non visible pour votre organisation
409	Conflit (ex. slug déjà pris, concurrence optimiste)
5xx	Erreur serveur

Un 404 peut signifier « existe mais pas pour vous » : l'isolation par tenant masque les ressources d'autres organisations plutôt que de révéler leur existence.

Multi-tenant¶

• L'organisation (tenant) est déduite de votre jeton (JWT) ou de votre clé API.
• Vous ne passez jamais d'tenantId en paramètre sur les surfaces authentifiées.
• Toutes les ressources sont cloisonnées : une requête ne peut lire/écrire que dans son organisation.
• Sur les surfaces internes (M2M), le tenant est au contraire porté par le corps, car il n'y a pas de jeton (voir Ponts M2M).

Sur les routes publiques anonymes¶

Certaines routes sont anonymes ([AllowAnonymous]) et identifient l'organisation par un slug dans l'URL : formulaire public (/api/forms/public/{slug}), espace Knowledge (/api/knowledge/public/spaces/{slug}), portail Careers (/api/careers/public/{slug}), boutique/RDV (/api/public/stores/{publicSlug}). Elles n'exposent jamais de secret ni d'tenantId.

Idempotence et concurrence¶

• Les actions de type « publier », « synchroniser un statut » sont conçues idempotentes : rejouer la même opération ne duplique rien.
• Certaines ressources utilisent une concurrence optimiste (jeton xmin PostgreSQL) ; un conflit remonte en 409 — réessayez après relecture.

Pagination et filtres¶

Selon les endpoints, les listes acceptent des filtres en query string (status, collectionId, projectId, month, tag…). Reportez-vous à la référence de chaque module.