API HTTP et REST : ce que l’hypermédia change pour les clients
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.
Article
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.
Une commande attend son paiement. Le client de votre API doit savoir qu’il peut payer, à quelle adresse et avec quels champs. S’il construit lui-même l’adresse de paiement et décide seul quand l’action est possible, un changement de cette adresse ou de ces conditions peut l’obliger à changer aussi. L’API peut plutôt lui fournir, dans la réponse, l’action disponible, sa destination et les champs attendus ; après le paiement, elle propose d’autres actions. Ce principe s’appelle HATEOAS. Il réduit ce que le client doit connaître à l’avance, sans le dispenser de comprendre le format des réponses ni le sens des actions, et sans dispenser le serveur de vérifier chaque demande.
La commande C-42 montre le principe à l’œuvre, de son attente de paiement jusqu’au paiement ; viennent ensuite sa place dans REST et le choix d’un format.
HATEOAS développe Hypermedia As The Engine Of Application State : l’hypermédia comme moteur de l’état de l’application. L’hypermédia désigne les liens et les actions contenus dans les réponses. Le nom décrit une façon de faire avancer un parcours : le client sait lire le format des réponses, le serveur y indique les possibilités disponibles, et le client passe d’une étape à la suivante en choisissant parmi elles.
Une action décrite dans un message est parfois appelée une affordance. Elle peut préciser une méthode HTTP, une adresse et les paramètres à fournir. Dans une page web, un formulaire remplit ce rôle.
Voici la réponse que reçoit le client pour la commande C-42, d’un montant de 120 €. Le contrat est fictif : le format JSON décrit le type et l’unité du montant, ainsi que les champs de l’action. Ces conventions doivent être documentées pour le client, car application/json ne les définit pas à lui seul.
{
"reference": "C-42",
"statut": "en_attente_de_paiement",
"total": {"centimes": 12000, "devise": "EUR"},
"_actions": {
"payer": {
"method": "POST",
"href": "/commandes/C-42/paiements",
"contentType": "application/json",
"champs": {
"moyenId": {"type": "string", "required": true},
"centimes": {"type": "integer", "const": 12000},
"devise": {"type": "string", "const": "EUR"},
"demandeId": {"type": "string", "required": true}
}
}
}
}
La réponse contient deux sortes d’informations. Les données disent où en est la commande : en attente de paiement, 12 000 centimes d’euro. L’action payer dit ce que le client peut demander maintenant : un POST à l’adresse /commandes/C-42/paiements, avec un corps JSON qui porte un moyen de paiement, le montant exact, la devise et un identifiant de demande. Le client découvre ainsi la destination de l’action au lieu de la fabriquer à partir d’un chemin enregistré dans son code.
Le client connaît la signification de « payer » et possède l’accord de l’acheteur pour ce montant. Il reprend la cible et le format indiqués :
POST /commandes/C-42/paiements
Content-Type: application/json
{"moyenId":"MP-7","centimes":12000,
"devise":"EUR","demandeId":"D-92"}
L’identifiant demandeId sert au mécanisme de déduplication défini par l’application : si la même demande D-92 arrive deux fois, le serveur la reconnaît et ne paie pas une seconde fois. L’article sur l’idempotence détaille ce mécanisme. Sa présence ne rend pas tous les POST idempotents : parmi les méthodes que définit la RFC 9110, ce sont PUT, DELETE et les méthodes sûres qui sont idempotentes, et POST n’en fait pas partie (§9.2.2).
Le serveur contrôle les droits, le moyen de paiement, le montant et la devise reçus, et l’état actuel de la commande : les valeurs imposées dans la représentation ne garantissent pas ce que contient le corps envoyé. Supposons que le paiement soit effectivement confirmé et que le contrat retourne la représentation actualisée de la commande :
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"reference": "C-42",
"statut": "payee",
"paiementId": "P-18",
"_liens": {
"suivi": {"href": "/expeditions/S-63"}
},
"_actions": {}
}
L’action « payer » a disparu et un lien de suivi est apparu. Le client n’invente pas ce lien en remplaçant « commandes » par « expeditions » dans l’adresse : il suit celui que la réponse lui donne. Si le paiement est seulement en cours, le serveur doit le dire et fournir le moyen d’en connaître l’issue ; une demande acceptée n’autorise pas le client à annoncer « payé ».
Une représentation décrit la commande au moment où elle a été produite. Une ancienne réponse peut donc encore proposer « payer » alors qu’un autre client vient de régler C-42. Les actions affichées ne remplacent pas les contrôles à l’exécution : le service doit retrouver la demande déjà traitée, grâce à son identifiant, ou refuser une nouvelle opération incompatible avec l’état réel. Si la réponse au paiement se perd en route, l’application doit aussi définir comment retrouver P-18 avant d’envisager un nouvel effet.
L’action ne décide pas davantage à la place du client. Elle lui dit ce qui est possible, pas ce qu’il doit faire : suivre un lien ne lui apprend pas s’il faut payer, annuler ou attendre. Ce choix dépend de son objectif, et de l’accord qu’il a reçu pour agir.
Le bénéfice attendu est de réduire le nombre d’adresses et de transitions codées à l’avance dans le client. Le serveur peut déplacer le paiement de C-42 ou retirer l’action quand elle n’a plus de sens, tant qu’il conserve le contrat que le client comprend.
Le type de média définit comment lire les données et les contrôles : où se trouvent les actions, ce que veulent dire method, href et champs. Le vocabulaire métier dit ce que signifie une action « payer », dans quelle unité les montants sont exprimés et quelles erreurs sont possibles. Un format partagé ne donne pas à lui seul toute cette connaissance. Fielding demande d’ailleurs qu’une API REST consacre presque tout son effort de description à ses types de média et à ses noms de relations (REST APIs must be hypertext-driven, 2008).
Le navigateur montre cette séparation, et sa limite. Il sait afficher le HTML et soumettre les formulaires ; la personne qui l’utilise comprend le contenu et décide quoi faire. Un client logiciel reçoit le même genre de contrôles, mais personne ne lit la page à sa place : la compréhension de « payer », qu’un humain apporte devant un formulaire, doit être écrite dans son code ou dans sa mission.
REST est un style d’architecture que Roy Fielding a formalisé dans sa thèse en 2000 : un ensemble de contraintes imposées aux clients, aux serveurs et à leurs échanges. La contrainte centrale, l’interface uniforme, oblige tous les composants à échanger de la même façon, quelle que soit la ressource. Fielding la décompose en quatre contraintes, dont l’hypermédia est la dernière (§5.1.5). Les trois autres se voient dans le même échange de C-42.
Identifier les ressources. Toute information qui peut être nommée peut être une ressource : une commande, un article, un compte. La commande C-42 est désignée de façon stable par une URI. Le choix de noms lisibles aide à comprendre une API, mais REST ne prescrit pas une grammaire de chemins fondée sur les noms plutôt que les verbes. Le client identifie la ressource et comprend le contrat, sans déduire de son adresse la méthode autorisée.
Manipuler par les représentations. Le client ne touche jamais la ressource : il échange des représentations, des messages qui la décrivent à un instant et dans un format donnés. Les deux réponses de C-42 en sont deux, avant et après le paiement. Une même ressource peut être servie en HTML à un navigateur et en JSON à un programme, selon les formats disponibles et les préférences que le client indique dans l’en-tête Accept (RFC 9110, §12.1).
Des messages auto-descriptifs. Chaque message porte de quoi être interprété. La méthode dit ce qui est demandé : GET demande une représentation, POST demande à la ressource de traiter le contenu envoyé selon ses propres règles, ici un paiement (RFC 9110, §9.3). Le type de média, dans l’en-tête Content-Type, dit comment lire le corps. Le statut dit ce qui s’est passé, avec un sens partagé : 200 pour un succès, 404 pour une ressource introuvable, 409 pour un conflit avec l’état actuel.
Ces règles communes ont un coût que Fielding reconnaît : une interface générale est moins efficace qu’une interface conçue pour un seul échange. En retour, les messages auto-descriptifs indiquent comment interpréter l’échange, et l’hypermédia fournit les transitions proposées. Fielding décrit l’application comme un moteur qui passe d’un état au suivant en choisissant parmi les transitions présentes dans les représentations reçues (§5.3.3). En 2008, il en tire une conséquence nette : une API dont l’état n’est pas piloté par l’hypertexte ne peut pas être dite REST.
Le format de C-42 est inventé pour l’exemple. Dans une vraie API, choisir un format publié impose de vérifier les contrôles qu’il sait exprimer. HAL décrit des liens, et JSON:API, dans sa version 1.1, des objets de lien ; ni l’un ni l’autre ne décrit, dans ses réponses, une action avec sa méthode et ses champs. Siren décrit des actions avec destination, méthode et champs. HAL-FORMS étend HAL avec des formulaires dynamiques ; il faut distinguer cette extension de HAL de base, centré sur les liens. Le nom d’un format ne suffit donc pas : vérifiez sa version et les propriétés que votre client comprend réellement.
Avec un format qui sait décrire l’action « payer », il reste à documenter le vocabulaire métier : le format dit où trouver les champs, pas ce que signifie un moyen de paiement ni pourquoi le montant est imposé.
Privilégiez cette approche lorsque plusieurs clients doivent suivre des parcours qui évoluent : des étapes ajoutées, des actions qui n’existent que dans certains états, des destinations qui changent. Elle demande de concevoir les réponses et les clients ensemble. Ajouter quelques liens à une API dont les consommateurs continuent à construire toutes les adresses ne procure pas le même bénéfice.
Sur C-42, le client a payé sans connaître l’adresse de paiement à l’avance, a vu l’action disparaître et le lien de suivi apparaître, et a suivi ce lien sans fabriquer d’adresse. Il lui a fallu en revanche connaître le format des actions, le sens de « payer », l’accord de l’acheteur, et savoir traiter un refus du serveur. HATEOAS déplace vers les réponses la connaissance des adresses et des étapes disponibles ; le reste du contrat demeure à la charge du client.
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.
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.
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.
Avec htmx, le serveur renvoie des fragments HTML prêts à afficher. Cette approche simplifie certains écrans, avec des limites pour les usages très riches.
Laisser un commentaire
Votre commentaire sera relu avant d'être publié.