Les réponses d’API doivent être claires, cohérentes et prévisibles pour faciliter le travail des intégrateurs et garantir une bonne expérience développeur.

Nous passons en revue les bonnes pratiques pour structurer vos réponses, gérer les codes d’état et assurer une communication uniforme sur l’ensemble de vos services.

- Règles RES -

RES‑01 : Le corps de réponse DOIT être proposé en format JSON.

RES‑02 : Le format de réponse par défaut DOIT être application/json.

RES‑03 : Le corps de réponse DEVRAIT être proposé en XML.

RES‑04 : Le corps de réponse PEUT être proposé dans un format alternatif.

RES‑05 : Le format du corps de la réponse et l’en-tête Content-Type DOIVENT être cohérents.

RES‑06 : La réponse à une requête GET de collection DEVRAIT être paginée.

RES‑07 : Les mots-clefs conventionnels pour la pagination DOIVENT être utilisés pour les endpoints paginés.

RES‑08 : Les informations de pagination DOIVENT être dans le corps de la réponse.

RES‑09 : Les mots-clés de pagination DOIVENT être cohérents de la requête à la réponse.

RES‑10 : L’attribut de limite de pagination DOIT avoir une valeur maximale autorisée.

RES‑11 : La pagination PEUT être proposée avec une logique de curseur.

RES‑12 : Des mots-clés standards DOIVENT être utilisés pour la pagination basée sur un curseur.

RES‑13 : Le nom du tableau dans la réponse DOIT correspondre au nom de la collection d’objets.

RES‑14 : Le corps de réponse NE DOIT PAS être vide, quel que soit le verbe.

RES‑15 : Le corps de réponse pour POST/PUT/PATCH DOIT contenir les détails des ressources créées/mises à jour.

RES‑16 : Les codes de réponse HTTP standards DOIVENT être utilisés de façon appropriée.

RES‑17 : Le corps de réponse DOIT suivre un format standard pour les codes de retour 4xx.

RES‑18 : Le code et la description dans le corps de réponse DEVRAIENT décrire précisément le code de retour.

RES‑19 : Le corps de réponse pour les codes 4xx PEUT contenir un lien vers une page de support ou d’aide.

RES‑20 : Le corps de réponse pour les codes 5xx NE DOIT PAS divulguer de détails techniques.

RES‑21 : Le statut des quotas/limites PEUT être retourné dans l’en-tête de la réponse.

RES‑22 : Les noms des en-têtes de quotas DOIVENT suivre les normes de l’IETF.