Guide de conception d’API REST

Une API est une promesse. Des qu’un client en depend, chaque bizarrerie que vous avez livree devient permanente, parce que quelqu’un quelque part a ecrit du code contre cette bizarrerie. J’ai maintenu des API pendant des annees et celles qui ont bien vieilli partageaient le meme trait : elles etaient ennuyeuses et previsibles. Voici comment j’y arrive.

Modelisez les ressources en noms, prenez les verbes a HTTP

L’URL devrait nommer une chose. La methode dit ce que vous lui faites. Je vois sans cesse des points d’entree comme /getUser et /createOrderNow, et ils combattent tout l’interet de HTTP. Une conception propre utilise des noms au pluriel pour les collections et laisse la methode porter l’action.

GET    /orders          liste les commandes
POST   /orders          cree une commande
GET    /orders/42       recupere une commande
PATCH  /orders/42       met a jour des champs
DELETE /orders/42       la supprime

GET    /orders/42/items ressource imbriquee

PATCH pour les mises a jour partielles et PUT pour le remplacement complet est une distinction a garder. La plupart des vraies mises a jour touchent quelques champs, donc PATCH est ce que je prends, et PUT devient le cas rare ou le client possede vraiment toute la representation.

Utilisez les codes de statut comme les clients l’attendent

Renvoyez le code de statut qui correspond a la realite. Un 200 sur une requete echouee parce qu’on « a mis l’erreur dans le corps » casse tout client generique et tout outil de supervision qui lit la ligne de statut. L’ensemble que j’utilise couvre presque tout :

• 200 pour une lecture ou une mise a jour reussie, 201 quand vous avez cree quelque chose.
• 400 pour une entree malformee, 422 quand l’entree est bien formee mais semantiquement invalide.
• 401 quand vous ne savez pas qui ils sont, 403 quand vous le savez et qu’ils n’ont pas le droit.
• 404 pour une ressource manquante, 409 pour un conflit comme un doublon.
• 500 uniquement pour de vraies pannes serveur, jamais pour une erreur du client.

Rendez les erreurs lisibles par la machine

Un corps d’erreur devrait aider le code appelant a reagir, pas juste afficher une chaine. Je renvoie un code machine stable a cote d’un message humain, pour que les clients puissent brancher sur le code sans analyser une prose que je pourrais reformuler plus tard.

{
  "error": {
    "code": "insufficient_funds",
    "message": "La carte a ete refusee.",
    "field": "payment_method"
  }
}

La coherence compte ici plus que l’ingeniosite. Chaque erreur de l’API devrait avoir la meme forme, pour qu’un client ecrive un seul gestionnaire d’erreur au lieu de dix. C’est le meme instinct que j’apporte aux logs, dont j’ai parle dans les bonnes pratiques d’observabilite : la structure vaut mieux que la prose quand autre chose doit la lire.

Prevoyez le versionnage avant d’en avoir besoin

Vous devrez faire un changement cassant tot ou tard. Decidez comment avant de livrer la v1. Je mets la version dans le chemin, /v1/orders, parce qu’elle est visible, cacheable et triviale a router. Le versionnage par en-tete est plus elegant sur le papier et plus penible en pratique quand quelqu’un debogue avec curl. Quel que soit votre choix, la regle est de ne jamais casser une version existante. Les ajouts comme de nouveaux champs optionnels vont bien. Retirer un champ ou changer son type est une nouvelle version.

Paginez et filtrez des le premier jour

Toute collection qui peut grandir grandira, et un GET qui renvoie dix mille lignes finira par expirer et emporter une base de donnees avec lui. J’ajoute la pagination a chaque point d’entree de liste des le depart, meme quand les donnees sont minuscules, parce que l’ajouter plus tard est un changement cassant. La pagination par curseur gere mieux les grands jeux de donnees mouvants que l’offset, qui derive quand des lignes sont inserees en cours de parcours.

• Renvoyez un curseur stable et un signal clair de « il y en a plus ».
• Autorisez le filtrage par parametres de requete, et documentez exactement quels champs sont filtrables.
• Plafonnez la taille de page cote serveur pour qu’un client ne puisse pas tout demander d’un coup.

Soyez strict sur ce que vous acceptez, genereux sur ce que vous renvoyez

Validez l’entree durement a la frontiere et rejetez tout ce qui est malforme avec un 400 ou 422 clair. Plus vous attrapez les mauvaises donnees pres du bord, moins elles peuvent corrompre l’aval, ce qui ramene directement aux contraintes sur lesquelles je m’appuie dans les bonnes pratiques de schema de base de donnees. Cote sortie, gardez les reponses stables et previsibles pour que les clients puissent faire confiance a la forme. Une API stricte a la porte et coherente a la sortie est une API qu’on aime construire, et cette bonne volonte est ce qui fait adopter votre plateforme.