Concevoir une API : contrat, ressources et statuts

Concevoir une API : contrat, ressources et statuts

1. Le contrat : ce qui engage, et envers qui

   Une API est un contrat commercial autant que technique. Toute forme de compatibilité promise devient une dette que l'on portera.

   Le contrat minimal qui tient

   • les ressources, nommées et non « les actions ». On manipule des objets, pas des verbes : la méthode HTTP exprime déjà l'action ;
   • les champs, leurs types, leur caractère obligatoire, et ce qui est modifiable par l'appelant ;
   • les codes de statut, par situation ;
   • la forme des erreurs, toujours la même, quelle que soit la route ;
   • les limites : taille maximale d'une requête, nombre d'éléments par page, débit.

   Un contrat qui omet ces cinq points produit des surprises, et chaque surprise se négocie au pire moment : à la mise en production d'un client.

   La forme d'erreur, décidée une fois

   Le format d'erreur est la partie la plus souvent improvisée, et la plus coûteuse. Il faut un format unique, valable pour toutes les routes, avec au minimum : un code stable que le client peut tester, un message destiné à être lu par un humain, et des champs de détail par valeur invalide. Le code d'erreur ne doit jamais être une phrase traduite : les clients testent sur le code, et un message d'erreur destiné aux utilisateurs finira par changer de formulation, ce qui cassera le client.

   La description machine de l'API

   Une spécification en OpenAPI décrit les routes, les paramètres, les types et les réponses dans un document structuré. Trois bénéfices concrets, dans cet ordre : un test qui vérifie que l'implémentation respecte la spécification, une documentation générée donc jamais périmée, et la possibilité d'un client généré automatiquement. Le dernier est le moins intéressant en soi — un client généré reste un client qu'on écrit.

2. Modeler les ressources, et non les actions

   La manière dont on nomme et découpe les ressources détermine l'evolution future de l'API. Une mauvaise structure de ressources ne se corrige pas sans casser les clients.

   L'erreur à ne pas commettre

   Une API qui expose POST /creerClient, POST /modifierClient, POST /supprimerClient n'expose pas des ressources : elle expose un RPC sur HTTP. Elle fonctionnera, et elle empêchera toute évolution, parce que chaque nouvelle opération imposera une nouvelle route ad hoc.

   La forme correcte expose des ressources — ici des clients — et laisse la méthode HTTP exprimer l'action. Ce changement n'est pas cosmétique : il est la différence entre une API qui évolue et une API qui s'épuise.

   Les Sept de REST, et leur usage réel

   • ressources nommées au pluriel : l'identifiant est dans le chemin ou dans la requête, jamais dans le corps d'un POST ;
   • sans état : chaque requête porte ce qu'elle doit savoir. C'est ce qui permet de passer d'un serveur à trois sans changer le client ;
   • un identifiant par ressource : un identifiant lisible n'est pas une mesure de sécurité, seulement de commodité ;
   • un code de statut par situation, pas un 200 accompagné d'un message d'erreur dans le corps ;
   • le bon contrat : en pratique, un schéma déclaré et vérifié ;
   • un seul point d'entrée pour une ressource, donc pas de GET et un POST qui font la même chose ;
   • les liens d'état : la documentation et les transitions d'état explicites, parce qu'un client ne devine pas ce qu'il peut faire ensuite.

   Ce sont des principes de conception, pas une checklist à cocher ligne par ligne. Une API peut tranquillement en violer trois et rester parfaitement exploitable ; l'erreur est de les violer par accident, sans savoir pourquoi.

3. Codes de statut et gestion d'erreur

   Les codes de statut sont la partie du contrat la plus sous-estimée. C'est pourtant le seul canal qui dise au client ce qu'il doit faire, sans qu'il ait à deviner.

   Le minimum à distinguer

   Code	Situation	Ce que fait un bon client
   400	demande invalide	corriger, ne pas réessayer à l'identique
   401	non authentifié	obtenir un jeton, réessayer une fois
   403	authentifié mais interdit	ne pas réessayer, avertir l'utilisateur
   404	ressource absente	ne pas réessayer
   409	conflit d'état	relire l'état, résoudre, réessayer
   429	débit dépassé	attendre et réessayer, en respectant l'en-tête de délai
   500	erreur serveur	réessayer avec temporisation croissante

   401 et 403 se confondent très souvent, et le client ne peut pas les traiter de la même façon. Un 401 doit déclencher une procédure de renouvellement de jeton ; un 403 ne le doit pas, et réessayer indéfiniment sur un 403 est exactement le comportement d'un client mal écrit. Le même raisonnement vaut pour 404 et 409.

   Ce qui n'est pas un code de statut

   Répondre 200 avec un corps {"erreur": "non autorisé"} est l'erreur la plus répandue des API internes. Elle rend l'API inexploitable pour tout client qui s'appuie sur le code — c'est-à-dire tous les clients générés, les bibliothèques de monitoring, les passerelles, et pour finir les humains.