Aller au contenu

Guides

Conventions de l’API

Adresse et format

Toutes les ressources sont sous /api/v1. Les corps sont en JSON UTF-8, les dates en ISO 8601 (UTC). Ignorez les champs inconnus : de nouveaux champs peuvent apparaître sans changement de version.

Isolation

L’organisation est déduite du jeton. Aucun paramètre ne permet d’en choisir une autre. Un identifiant appartenant à une autre organisation répond 404.

Pagination

Les listes acceptent limit (1 à 100, 25 par défaut) et cursor. La réponse contient pagination.nextCursor, opaque, ou null sur la dernière page. Le tri est stable : les ajouts pendant le parcours n’entraînent ni doublon ni saut. Un curseur modifié répond invalid_cursor.

Erreurs

Les erreurs suivent la RFC 9457 (application/problem+json) :

{
  "type": "https://<documentation>/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This operation requires the scope users:write.",
  "code": "insufficient_scope",
  "instance": "c8b1f0d2-…"
}

Basez votre logique sur status et code, jamais sur detail. Communiquez instance (identifiant de requête) au support. Les erreurs de validation listent les champs dans errors[]. La liste des codes figure dans Erreurs.

Idempotence

Les créations exigent l’en-tête Idempotency-Key (8 à 128 caractères parmi lettres, chiffres et _ . : -). La clé est conservée 24 heures par client :

Une requête en échec libère sa clé : corrigez-la et réessayez avec la même clé.

Limites de débit

Chaque client dispose par défaut de 600 requêtes par minute. Les en-têtes RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset indiquent l’état courant. Au-delà, l’API répond 429 avec Retry-After en secondes.

Une indisponibilité temporaire de la plateforme répond 503 temporarily_unavailable avec Retry-After : votre jeton reste valable, réessayez. Le serveur OAuth répond de même temporarily_unavailable sans révoquer votre autorisation.

Versionnement

La version majeure figure dans l’URL. Une version ne reçoit que des ajouts compatibles. Un changement incompatible crée /api/v2, servie en parallèle au moins douze mois. Une opération dépréciée renvoie les en-têtes Deprecation, Sunset et un lien vers le guide de migration.