← API REST : concevoir, mûrir, documenter

Niveau 3 : HATEOAS, le sommet de la maturité REST

≈ 20 minutes · Jalon M4 · Prérequis : Niveau 2 : exploiter les verbes HTTP

Le gain du jour : comprendre HATEOAS — la contrainte REST la plus citée et la moins appliquée — et savoir pourquoi elle change la relation entre client et serveur.

HATEOAS : un acronyme à décortiquer

HATEOAS = Hypermedia As The Engine Of Application State. Traduction : l’hypermédia comme moteur de l’état de l’application. L’idée : une réponse d’API ne doit pas seulement contenir des données, mais aussi des liens décrivant les actions possibles depuis cet état — exactement comme une page web contient des liens <a> vers les pages suivantes.

Reprenons l’exemple du niveau 2 :

// GET /orders/7  (niveau 2 — données seules)
{
  "id": 7,
  "status": "pending",
  "total": 42.50
}

Le client doit déjà savoir, en dehors de la réponse — via une documentation lue à part — qu’une commande pending peut être annulée via DELETE /orders/7. Cette connaissance est codée en dur dans le client.

// GET /orders/7  (niveau 3 — HATEOAS)
{
  "id": 7,
  "status": "pending",
  "total": 42.50,
  "_links": {
    "self": { "href": "/orders/7" },
    "cancel": { "href": "/orders/7", "method": "DELETE" },
    "customer": { "href": "/users/42" }
  }
}

Maintenant, le serveur dit au client quelles transitions sont possibles à partir de cet état précis. Si la commande passe au statut shipped, le lien cancel disparaîtra tout simplement de la réponse — le client n’a plus besoin de connaître à l’avance la règle métier « on ne peut annuler qu’une commande en attente », il lui suffit de regarder si le lien est présent.

Pourquoi c’est puissant : le découplage ultime

Sans HATEOAS, si le serveur déplace une ressource de /orders/7 à /v2/orders/7, tous les clients cassent — ils ont l’ancienne URI codée en dur. Avec HATEOAS, tant que le client suit toujours les liens fournis par le serveur (plutôt que de reconstruire des URI lui-même), le serveur peut réorganiser ses URI relativement librement : le client suivra simplement les nouveaux liens.

C’est la dernière contrainte de Fielding, et la plus radicale : le client ne doit connaître qu’une seule URI fixe au départ (le point d’entrée de l’API) ; tout le reste — actions disponibles, ressources liées, pagination — doit se découvrir dynamiquement via les liens des réponses.

Pourquoi si peu d’API l’adoptent

En pratique, HATEOAS reste rare, y compris chez des API très matures :

• Il complexifie le client : au lieu de coder une URI en dur, il faut parser une structure de liens et la suivre dynamiquement.
• Il n’existe pas de format universellement adopté : HAL (_links), JSON:API, Siren, Collection+JSON proposent chacun leur propre convention — contrairement à JSON lui-même, aucune n’a gagné une adoption massive.
• Le bénéfice se voit à long terme (refactoring d’URI sans casser les clients), pas à court terme — beaucoup d’équipes préfèrent la simplicité immédiate du niveau 2.

Vérifie ta compréhension

À toi de jouer

1. Reprends la réponse GET /orders/7 du niveau 2 (leçon précédente) et ajoute-lui une section _links avec au moins trois liens pertinents : voir le client, annuler la commande (si applicable), voir la facture.

2. Réfléchis à un cas où le lien cancel devrait disparaître de la réponse selon l’état de la commande (pending, shipped, delivered) — écris les trois réponses JSON correspondantes.

Pour aller plus loin

📖 Source principale : Martin Fowler, « Richardson Maturity Model », section « Level 3: Hypermedia Controls » — et, pour aller plus loin, la spécification du format HAL, l’une des conventions _links les plus utilisées en pratique.