REST API avec Spring MVC

Une application web finit toujours par avoir des clients qui ne sont pas des navigateurs. Une application mobile, un tableau de bord en React, un script d'import nocturne, un partenaire qui synchronise son catalogue. Aucun de ces clients ne veut du HTML : ils veulent des données, et une façon fiable de savoir si l'opération a réussi.

Le réflexe consiste à renvoyer du JSON depuis les contrôleurs existants et à considérer le travail terminé. C'est là que les API mal conçues naissent, et le symptôme est toujours le même : tout répond 200. Une ressource inexistante renvoie 200 avec un corps null. Une validation échouée renvoie 200 avec un champ "erreur" dans le JSON. Une exception renvoie 200 avec un corps vide. Le client ne peut alors plus rien décider automatiquement ; il doit inspecter le contenu pour deviner ce qui s'est passé, et chaque client le devine différemment.

Le code de statut HTTP n'est pas une décoration : c'est le seul canal que tous les clients, toutes les bibliothèques HTTP et tous les intermédiaires réseau comprennent sans convention préalable. Un 404 est traité correctement par un cache, un 429 déclenche une nouvelle tentative dans un client bien écrit, un 201 avec un en-tête Location indique où se trouve la ressource créée. Renvoyer 200 partout, c'est refuser d'utiliser un protocole qu'on paie déjà.