Article

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.

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.

Deux clients pour payer la même commande

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.

Premier changement : le paiement déménage

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 suivanteRésultat de l’exemple
A, adresse construitePOST vers l’ancienne route404 : il faut mettre à jour A ou maintenir l’ancienne route côté serveur.
B, action reluePOST vers le href reçuPaiement 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.

Quatre niveaux de Richardson : transport HTTP, ressources, méthodes et statuts HTTP, contrôles hypermédia. Ils ne certifient ni la qualité ni toutes les contraintes REST.
Le modèle de Richardson situe les contrôles hypermédia au niveau 3. Il ne constitue pas une certification de qualité ni la définition complète de REST.

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.

Deuxième changement : un justificatif devient obligatoire

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.

Une recette qui vérifie l’indépendance réelle

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.

  1. Déplacer uniquement la destination. Vérifier dans les traces que B appelle le nouveau href sans modification de son code ; constater le comportement de A lorsque l’ancienne route disparaît.
  2. Ajouter le champ obligatoire. Vérifier que B le présente ou signale précisément l’information manquante, et qu’aucun client n’invente une valeur pour poursuivre.
  3. Retirer l’action après paiement. Vérifier que B cesse de la proposer et que le serveur refuse aussi une demande devenue invalide provenant d’un client ancien.
  4. Couper la réponse après l’envoi. Le client ne sait alors pas si le paiement a eu lieu. Vérifier qu’il retrouve la demande initiale, par un identifiant de demande si le contrat en prévoit un, et applique le contrat de reprise. Une commande lue « à payer » ne suffit pas à autoriser un second paiement tant que le premier reste d’issue inconnue : il peut être encore en cours, ou l’état lu en retard. L’hypermédia ne règle pas à lui seul ces reprises, qui relèvent de l’idempotence.

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.

Choisir selon les changements que les clients doivent absorber

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

Sur le même sujet

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.

Laisser un commentaire

Elle n'est jamais affichée ni publiée. Elle sert à regrouper vos commentaires et, si vous vous inscrivez un jour avec elle, à vous les rendre.

Votre commentaire sera relu avant d'être publié.