The Design of Web APIs

1Le Kitchen Radar : concevez pour qui s'en sert

Lauret ouvre sur un four à micro-ondes rebaptisé « Kitchen Radar », dont la seule commande est un bouton « MAG. » qu'il faut maintenir enfoncé selon un timing précis pour doser la puissance du magnétron. Pour réchauffer votre soupe, vous devez devenir expert en magnétron. « L'interface tournée vers l'intérieur force les utilisateurs à devenir des experts du magnétron. » C'est exactement ce que font la plupart des APIs : elles exposent leur mécanique interne au lieu de ce que l'utilisateur veut faire.

La règle qui traverse tout le livre : on conçoit du point de vue du consommateur. Les gens ne veulent pas « allumer le magnétron », ils veulent « réchauffer un plat ». Une bonne API, c'est le serveur de restaurant qui cache la cuisine, pas le chef qui vous hurle la recette.

2Recettes et ingrédients : décidez QUOI avant COMMENT

Avant de choisir la moindre URL ou le moindre verbe HTTP, Lauret vous fait lister, en langage courant, ce que les utilisateurs veulent accomplir. Sa méthode tient dans un tableau, l'« API Capabilities Canvas » : utilisateur, cas d'usage, étape, entrée, succès, échec, opération.

Sa formule : « les cas d'usage sont des recettes, et les opérations sont leurs ingrédients génériques ». L'opération bien pensée est générique (« chauffer un aliment à une puissance et une durée données »), pas spécifique (« chauffer du lait et du chocolat »). Séparer le QUOI (les capacités, en français) du COMMENT (REST, HTTP) empêche les réflexes d'implémentation de déformer le design dès le départ.

3Votre API n'est pas votre base de données

Le péché le plus courant : recopier la base dans l'API. Une colonne nommée CUSD, une table renvoyée telle quelle, un supplier.phone exposé juste parce qu'il est stocké.

La règle de Lauret : la donnée que vous échangez est une représentation, pas une copie de votre stockage. « Concentrez-vous sur la donnée échangée du point de vue du métier, pas du stockage. » Les noms, les types, la structure peuvent tous différer entre l'API et la base ; c'est l'implémentation qui fait la traduction. Le consommateur doit voir un champ clair comme découvertAutorisé : actif, jamais un nom de colonne brut comme CUSD ni le schéma de vos tables.

4L'effet « wow » : des noms prévisibles donnent des super-pouvoirs

Un bon nom permet à un développeur de deviner le reste. Lauret le dit ainsi : « un design d'API intuitif donne des super-pouvoirs aux développeurs, ils peuvent deviner les données et les opérations disponibles. » Il montre le nettoyage d'un vrai champ bancaire : ACTBLNDFPRTFTBKACC devient, étape par étape, overdraftFacility.active.

Et être interopérable, c'est réutiliser les standards existants au lieu d'inventer les siens :

• IBAN pour un compte ;
• ISO 8601 pour une date (1982-12-20T10:31:00Z plutôt qu'un timestamp Unix illisible) ;
• GeoJSON pour des coordonnées.

Un développeur qui connaît déjà le standard n'a aucune documentation à lire. Le contraste tient dans une réponse JSON :

// ✗ deviné par personne           // ✓ deviné par tous, et standard
{ "ACTBLNDFPRTFTBKACC": true,      { "overdraftFacility": { "active": true },
  "dt": 1671531060 }                  "createdAt": "1982-12-20T10:31:00Z" }

// ✗ 400 Bad Request   (vide : au consommateur de deviner)

// ✓ 400 + application/problem+json : TOUT, d'un coup
{ "type": "validation-error",
  "errors": [
    { "field": "email", "issue": "format invalide" },
    { "field": "age",   "issue": "doit être >= 18" }
  ] }

// ✗ binaire : le jour où "en attente" arrive, executed ne suffit plus
{ "executed": true }

// ✓ extensible : ajouter une valeur ne casse aucun client
{ "status": "executed" }   // puis "pending", "cancelled"…

Trois choses que je ne savais pas

• Tout le livre tourne sur trois APIs fictives suivies du début à la fin : un réseau social, une boutique en ligne et une banque. Du coup chaque principe a le même exemple concret qui revient, et on voit la même API se transformer au fil des chapitres. C'est répétitif, mais ça ancre.
• Lauret conçoit « design-first » : on écrit la spécification OpenAPI PENDANT qu'on conçoit, comme outil de réflexion, pas comme documentation rédigée après coup. Et on la passe ensuite au linter (Spectral) exactement comme on linte du code, pour faire respecter les règles automatiquement. Il prévient quand même : ne commencez pas l'OpenAPI trop tôt, ça force une pensée REST prématurée.
• Sur la gouvernance, il a une formule : des règles d'API doivent être un facilitateur, pas « la police de l'API qui hurle sur les gens qui ne suivent pas les règles ». Et sur l'IA (nouveauté de cette édition 2025) : apprenez les fondamentaux avant de dépendre d'une IA, « car l'IA peut produire des réponses fausses, inexactes ou incomplètes ».

Toujours valable en 2026 ?

Plus que jamais, et pour une raison qui tombe à pic. Les APIs ne sont plus seulement consommées par des humains et leurs applis : elles le sont par des agents IA, à qui on donne des « outils » à appeler. Or un agent a exactement les mêmes besoins qu'un développeur humain, en pire : une API prévisible, bien nommée, qui se décrit elle-même. Tout ce que ce livre vous apprend à faire pour le « wow » d'un développeur, c'est précisément ce qui permet à un LLM d'appeler le bon endpoint avec les bons paramètres. Lauret l'a vu venir dans cette édition. Son obsession du point de vue du consommateur s'étend naturellement à un consommateur qui n'est pas humain.

Pour qui ?

Pour aller plus loin

Les idées de ce livre se prolongent dans mes cours gratuits : construire et déployer un vrai service dans le cours sur le déploiement, et l'art de relire ce que produit une machine dans Coder avec l'IA, où une API claire devient justement le contrat qu'un agent peut suivre sans se tromper.