HATEOAS : une API qui indique les actions disponibles
Une réponse hypermédia contient des données, des liens et des actions. Le client suit ces indications, tout en partageant un vocabulaire clair avec le serveur.
Article
Deux clients face à un paiement déplacé puis à un champ obligatoire : ce que l’hypermédia protège et ce qu’il laisse à la charge du client.
Une API HTTP peut être bien documentée et pourtant obliger tous ses clients à changer lorsque le paiement déménage. L’hypermédia réduit cette dépendance en transmettant les actions disponibles dans les réponses : un client qui les lit suit la nouvelle adresse sans être modifié. Quand le serveur exige une information nouvelle, ce client peut la demander ou signaler qu’elle manque, mais pas l’inventer.
Deux clients d’une même commande le montrent : le premier construit ses adresses, le second lit les contrôles reçus. Un déplacement d’URL puis l’ajout d’un champ obligatoire révèlent ce que chacun doit encore connaître. Une recette permet ensuite de vérifier cette indépendance sur votre propre API.
L’exemple est fictif. La commande C-42 attend un paiement de 120 euros. Les deux clients disposent des mêmes droits et connaissent le sens de l’action « payer ». Ils diffèrent par la façon dont ils trouvent l’adresse du paiement. Chaque comparaison repart d’une copie de la commande encore impayée, et A et B sont essayés séparément.
Le client A a été écrit à partir d’un contrat OpenAPI, un document qui décrit les opérations d’une API HTTP : leurs chemins, leurs méthodes et les schémas de leurs données. Son code contient le modèle de chemin du paiement et construit /commandes/C-42/paiement à partir de la référence de la commande.
Le client B ne contient aucun chemin de paiement. Il connaît un format de représentation qui décrit des contrôles hypermédia : des actions placées dans la réponse, avec leur destination, leur méthode et leurs champs. Il lit ces informations dans la réponse de la commande. Voici celle qu’il reçoit. Ce format JSON est inventé pour l’explication : les mots actions, payer et fields font partie d’un contrat partagé entre le client et le serveur, pas d’une convention que tout client JSON comprendrait spontanément.
{
"reference": "C-42",
"statut": "a-payer",
"actions": {
"payer": {
"href": "/commandes/C-42/paiement",
"method": "POST",
"type": "application/json",
"fields": [
{"name": "montant", "value": 120},
{"name": "devise", "value": "EUR"}
]
}
}
}
A et B envoient alors la même requête, un POST vers /commandes/C-42/paiement avec le corps {"montant":120,"devise":"EUR"}. A l’a construite d’après son code ; B l’a construite d’après l’action. Pour B, la présence de l’action indique un parcours proposé dans cet état de la commande. Le serveur vérifie encore les droits, le montant et l’état réel au moment du paiement : un lien reçu ne vaut jamais autorisation de contourner ces contrôles. Tant que rien ne change côté serveur, les deux clients se comportent de la même façon.
Le serveur déplace maintenant le paiement vers /encaissements?commande=C-42, sur le même domaine. Il conserve la méthode et le corps attendus, mais retire l’ancienne route. Dans la nouvelle réponse de la commande, seule la valeur de href change. Ni A ni B n’ont été modifiés.
| Client inchangé | Requête suivante | Résultat de l’exemple |
|---|---|---|
| A, adresse construite | POST vers l’ancienne route | 404 : il faut mettre à jour A ou maintenir l’ancienne route côté serveur. |
| B, action relue | POST vers le href reçu | Paiement accepté : aucune nouvelle adresse n’a été codée dans B. |
A échoue parce que l’adresse vient de son code, et que son code date d’avant le changement. Le serveur ne trouve plus rien à l’ancienne adresse et répond 404, le statut d’une ressource cible introuvable (RFC 9110, §15.5.5). B réussit parce que l’adresse vient de la réponse, produite après le changement.
B ne gagne cette indépendance que s’il relit réellement la représentation. S’il mémorise la destination indéfiniment, ou reconstruit le chemin à partir de la référence de la commande, il réintroduit la dépendance de A. Un cache doit donc respecter les règles de fraîcheur du service. Un déplacement vers un autre domaine demanderait en plus de vérifier la politique de confiance et de transmission des identifiants, que l’exemple écarte en restant sur le même domaine.
Le fournisseur pouvait aussi garder l’ancienne route sans hypermédia. Il aurait alors payé la compatibilité dans le serveur, route par route. L’hypermédia répartit le travail autrement : le serveur choisit la destination courante, le client implémente les règles de lecture des contrôles. C’est le rôle que Fielding attribue aux types de média et aux relations pour permettre l’évolution indépendante. Dans le même billet de 2008, il écrit qu’une API REST ne doit pas fixer à l’avance des noms de ressources ni leur hiérarchie : c’est exactement ce que le code de A suppose.
Le modèle de maturité présenté par Fowler nomme cette différence. A et B illustrent les deux premiers niveaux, des ressources et des méthodes HTTP ; seul B illustre le troisième, en lisant des contrôles hypermédia. Au sens du billet de Fielding, seul le parcours de B est piloté par l’hypertexte. Fowler en donne le bénéfice : le serveur peut changer son schéma d’URI sans casser ses clients. Les autres contraintes de REST sont développées dans l’article sur les six contraintes du style.
Le paiement exige désormais un numéro de bon de commande, numeroBon. B reçoit ce champ supplémentaire dans la description de l’action :
{
"name": "numeroBon",
"type": "text",
"required": true,
"label": "Numéro du bon de commande"
}
A continue d’envoyer son ancien corps, et le serveur rejette la demande comme incomplète. B voit le nouveau champ, mais le voir ne suffit pas à le remplir. Si son moteur de formulaires comprend déjà les propriétés required et label, il peut afficher un champ obligatoire à un utilisateur, qui fournit le numéro. Un B entièrement automatique, sans accès à cette information ni règle pour la retrouver, doit en revanche s’arrêter et demander une intervention.
Si le nouveau champ était une confirmation de consentement, le client ne pourrait pas davantage la cocher de sa propre initiative : le consentement appartient à l’utilisateur. Le sens métier, l’autorité de l’utilisateur et les données disponibles restent nécessaires. Un contrôle hypermédia rend le changement visible ; il ne garantit pas que chaque ancien client puisse l’exécuter.
Avant de généraliser cette architecture, conservez la version précédente de chaque client pour une recette sur un environnement de test. Les scénarios proposés ici ne sont pas des mesures réalisées sur une API existante.
Les deux premières épreuves isolent les deux évolutions de l’exemple : une évolution d’adresse et une évolution du contrat d’entrée. Les deux suivantes empêchent de confondre la découverte d’une action, la validité de cette action et le résultat effectivement obtenu.
Pour une équipe qui livre client et serveur ensemble, gardez un contrat HTTP documenté si les migrations coordonnées coûtent peu : quand le paiement déménage, la même livraison met à jour A. OpenAPI ne s’oppose d’ailleurs pas à l’hypermédia. Il peut décrire le schéma de réponses qui contiennent des actions, et il distingue ses propres liens, connus à la conception, des liens fournis dans la réponse (OpenAPI, Link Object).
Pour plusieurs clients livrés séparément, privilégiez les contrôles hypermédia sur les parcours dont les destinations et les actions disponibles changent. Le coût à accepter est un lecteur de contrôles, des règles de compatibilité du format et une gestion explicite des actions inconnues. Des liens ajoutés aux réponses n’apportent aucune indépendance si aucun client ne les lit.
Les deux changements de C-42 délimitent ce que l’hypermédia apporte. Le déplacement du paiement a cassé A et laissé B intact, parce que B tenait son adresse de la réponse. Le champ obligatoire a fait refuser la demande de A, et n’a laissé passer B que lorsqu’un utilisateur pouvait fournir le numéro. Le critère de choix se lit donc dans les évolutions que vous prévoyez : si ce sont surtout des destinations, ou des actions exprimables dans le contrat que B comprend déjà, des clients comme B les traversent sans nouvelle livraison, alors qu’une action métier nouvelle demande encore que le client en connaisse le sens ; si ce sont des données que seul l’utilisateur détient, chaque client devra de toute façon les obtenir.
Explorer
Choisis dans l’index d’après les étiquettes de cet article — les plus proches d’abord, hors de sa série. Rien n’est écrit à la main : un article publié demain avec les mêmes étiquettes y prendra place.
Une réponse hypermédia contient des données, des liens et des actions. Le client suit ces indications, tout en partageant un vocabulaire clair avec le serveur.
Retard des données, service indisponible : quand servir une copie, refuser ou différer une demande ? Un exemple d’API explique les réponses HTTP.
Un agent peut suivre les liens et les actions d’une API hypermédia. Voici comment cela fonctionne, ce que MCP apporte et les critères utiles pour choisir.
Laisser un commentaire
Votre commentaire sera relu avant d'être publié.