Retard des données ou API indisponible : que répondre ?
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.
Article
Que demande REST à une API ? Six contraintes d’architecture, leurs avantages et leurs coûts, puis un échange HTTP pour examiner cache, liens et actions.
Votre API renvoie la commande C-42 en JSON quand un client envoie
GET /commandes/C-42. Est-ce une API REST ? Ni JSON ni le choix des méthodes HTTP ne permettent de le dire. REST est un style d’architecture : des contraintes, formalisées par Roy Fielding en 2000, qui portent sur les clients, les serveurs et leurs échanges. Chacune retire une liberté pour obtenir une propriété. La plus importante, l’interface uniforme, demande que les réponses indiquent elles-mêmes au client ce qu’il peut faire ensuite. Pour juger une API, regardez donc comment ses clients découvrent les actions, utilisent le cache et résistent aux évolutions du serveur.Une réponse minimale pour C-42 s’enrichit ici, contrainte après contrainte, de ce que REST exige ; le navigateur montre ensuite ce que ces contraintes rendent possible.
Voici la réponse la plus simple que votre API puisse renvoyer pour C-42. L’échange est fictif ; il sert de fil à tout l’article.
GET /commandes/C-42
HTTP/1.1 200 OK
Content-Type: application/json
{"reference":"C-42","statut":"payee"}
Trois notions se croisent dans cet échange. HTTP définit la forme des échanges sur le réseau : la méthode GET, le statut 200 et les en-têtes. JSON est le format des données du corps. REST n’apparaît nulle part dans le message, parce qu’il décrit l’organisation du système entier, clients, serveurs et intermédiaires compris. Une API peut employer HTTP et JSON sans respecter les contraintes de REST, et l’inverse existe aussi :
Ce qui distingue une API REST se lit autour des données : ce que la réponse dit de sa réutilisation par un cache, du sens de l’opération et des liens qu’elle propose. Ces informations décident de ce qu’un client ou un intermédiaire peut faire sans connaître l’implémentation du serveur. La réponse minimale de C-42 n’en contient presque aucune.
Un style d’architecture est un ensemble de règles choisies pour obtenir certaines propriétés. REST, pour Representational State Transfer, a été formalisé par Roy Fielding dans sa thèse publiée en 2000. Fielding a participé dans les mêmes années à la rédaction des spécifications de HTTP et des URI, les identifiants des ressources, et sa thèse décrit comment ces contraintes ont guidé l’architecture du Web. Cette origine explique la place qu’occupent dans REST le navigateur, les liens et les intermédiaires du réseau : il s’agissait de permettre à des composants développés séparément de communiquer et d’évoluer.
Le chapitre 5 de la thèse part d’un système sans aucune contrainte et lui en applique une à la fois, chacune justifiée par la propriété qu’elle apporte et discutée avec ce qu’elle coûte. Les sections suivantes appliquent le même ordre à C-42.
La première contrainte sépare le client du serveur. L’application qui affiche C-42 s’occupe de l’interface ; le serveur s’occupe des données et des règles. Le serveur peut changer de base de données, l’application peut être réécrite pour un téléphone, tant que leurs échanges restent les mêmes. Fielding en attend une interface portable d’une plateforme à l’autre, un serveur plus simple, donc plus facile à faire monter en charge, et surtout des composants qui évoluent séparément.
La deuxième rend la communication sans état : chaque requête doit contenir tout ce qu’il faut pour la comprendre, sans s’appuyer sur un contexte conservé par le serveur entre deux requêtes. L’adresse /commandes/C-42 désigne explicitement la commande, mais cela ne suffit pas : l’échange est sans état si la requête apporte aussi tout le contexte nécessaire, sans dépendre d’une conversation mémorisée par le serveur. Supposons au contraire un parcours où le client choisit d’abord une commande, que le serveur garde dans la session, puis demande GET /commande-courante : cette seconde requête ne se comprend qu’avec la sélection mémorisée, et enfreint la contrainte. La contrainte ne signifie pas que le serveur oublie les commandes ou les comptes qu’il stocke. Elle vise l’état de la conversation, que Fielding place entièrement chez le client.
Le serveur y gagne trois choses : un outil de surveillance comprend une requête sans reconstituer celles qui l’ont précédée ; il est plus simple de se remettre d’une panne partielle ; et le serveur n’a aucun état de conversation à conserver pour la requête suivante, ce qui facilite la montée en charge. Le prix est une répétition, puisque chaque requête transporte à nouveau le contexte dont elle a besoin. Fielding relève un second coût : l’état de l’application étant chez le client, le comportement de l’ensemble dépend de la bonne mise en œuvre de chaque version des clients.
Répéter le contexte dans chaque requête coûte du réseau. Pour regagner cette efficacité, Fielding ajoute la contrainte du cache : les données d’une réponse doivent être marquées, explicitement ou implicitement, comme réutilisables ou non. Un cache peut alors répondre à la place du serveur et supprimer une partie des échanges. Le risque est une copie trop ancienne servie à la place d’une réponse à jour, qui rend le système moins fiable. HTTP exprime cette marque par l’en-tête Cache-Control, détaillé plus bas sur l’échange enrichi de C-42.
Vient ensuite l’interface uniforme, que Fielding désigne comme le trait central du style. Toutes les ressources s’échangent de la même façon : une commande, un article ou un compte se lisent avec les mêmes méthodes, les mêmes en-têtes et les mêmes statuts. Fielding la décompose en quatre contraintes, que l’échange de C-42 permet de montrer.
/commandes/C-42. REST ne prescrit pas la forme de ce chemin. En 2008, Fielding écrit même qu’une API REST ne doit pas fixer à l’avance des noms de ressources ni leur hiérarchie : le serveur reste maître de ses adresses.Accept la représentation qui lui convient.Content-Type indique le type de média du corps, Cache-Control dit si la réponse peut être réutilisée. Un intermédiaire comprend ainsi l’échange sans connaître l’application.Fielding a insisté sur cette dernière contrainte en 2008, dans un billet au titre explicite, REST APIs must be hypertext-driven : si l’état de l’application n’est pas piloté par l’hypertexte, l’API ne peut pas être dite REST. Il y précise ce qu’un client doit connaître au départ : une adresse d’entrée et des types de média standardisés, adaptés au public visé. Les adresses et les transitions viennent ensuite des réponses ; le sens des types de média et des relations reste une connaissance préalable du client, comme Fielding le rappelle dans ses réponses aux commentaires du billet.
L’interface uniforme a un prix, que Fielding nomme lui-même : elle « dégrade l’efficacité », puisque l’information circule sous une forme standardisée au lieu d’être ajustée aux besoins de chaque application. En échange, les implémentations sont découplées des services qu’elles rendent, et chacune peut évoluer sans attendre les autres.
La cinquième contrainte organise le système en couches : chaque composant ne voit que la couche avec laquelle il échange. L’application qui demande C-42 ne sait pas si sa réponse vient du serveur d’origine, d’un répartiteur de charge ou d’un cache placé devant lui. Ces intermédiaires peuvent être insérés sans modifier le client, parce que les messages sont auto-descriptifs : un cache lit Cache-Control sans rien savoir des commandes. Chaque couche ajoute en revanche du traitement et de la latence.
La sixième, le code à la demande, est facultative. Elle permet au serveur d’étendre le client en lui envoyant du code à exécuter, comme le JavaScript d’une page web. Fielding la laisse facultative parce qu’elle réduit la visibilité : un intermédiaire ne sait plus ce que le client fera du code reçu.
Le tableau réunit les six contraintes avec ce qu’elles interdisent, ce qu’elles apportent et ce qu’elles coûtent.
| Contrainte | Ce qu’elle interdit | Ce qu’elle apporte | Ce qu’elle coûte |
|---|---|---|---|
| Client-serveur | lier l’interface au stockage des données | les deux évoluent séparément ; un serveur plus simple | aucun coût n’est discuté au chapitre 5 |
| Sans état | un contexte de session conservé par le serveur et nécessaire pour comprendre la requête | chaque requête se comprend seule : surveillance, reprise après panne, montée en charge | le contexte est répété à chaque requête ; le serveur dépend du comportement des clients |
| Cache | laisser indéterminé si une réponse est réutilisable | des intermédiaires répondent à la place du serveur | une copie périmée peut être servie |
| Interface uniforme | un mode d’accès taillé pour chaque type de ressource | un client générique et des composants qui évoluent indépendamment ; c’est la contrainte centrale du style | elle « dégrade l’efficacité » : l’information circule sous une forme standardisée |
| Système en couches | dépendre de composants au-delà de la couche avec laquelle le client échange | des intermédiaires, caches partagés ou répartiteurs de charge, insérés sans modifier le client | du traitement et de la latence à chaque couche |
| Code à la demande (facultative) | rien d’obligatoire : elle ajoute une possibilité | le serveur étend le client après coup, par exemple avec le JavaScript d’une page | moins de visibilité pour les intermédiaires, d’où son caractère facultatif |
Voici la réponse de C-42 enrichie de ce que plusieurs contraintes rendent visible dans un message : un contrat de cache explicite et un lien reçu. Elle ne prouve pas à elle seule que l’architecture est REST. Elle suppose un contrat connu du client, qui définit le sens des relations et leurs traitements, des requêtes qui apportent leur propre contexte, et des composants qui se comportent comme prévu. Le corps reste un format métier fictif ; les en-têtes sont ceux de HTTP.
GET /commandes/C-42
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private, no-cache
ETag: "c42-v7"
Vary: Accept
{"reference":"C-42","statut":"payee",
"liens":{"suivi":"/expeditions/S-63"}}
Content-Type indique le type de média du corps, donc comment le décoder (RFC 9110, §8.3). Le sens de « suivi » reste en revanche défini par le contrat métier de l’API, car application/json ne dit rien des relations entre ressources. Vary: Accept signale aux caches que la réponse dépend du format demandé : une version HTML de la même commande ne doit pas être servie à ce client (§12.5.5).
Cache-Control porte la marque qu’exige la contrainte du cache, et ses deux directives se lisent séparément (RFC 9111, §5.2.2). private interdit à un cache partagé, celui d’un intermédiaire, de stocker la réponse, qui ne concerne qu’un seul client. no-cache ne veut pas dire « ne rien stocker » : un cache peut garder la réponse, mais ne doit pas la réutiliser sans l’avoir fait valider par le serveur. Ne rien stocker du tout relève de no-store.
La validation s’appuie sur l’ETag, l’étiquette de la version de la représentation (RFC 9110, §8.8.3). Le cache privé de l’application redemande C-42 avec If-None-Match: "c42-v7" (§13.1.2). Si l’étiquette correspond encore à celle de la représentation sélectionnée, le serveur répond 304 Not Modified à ce GET conditionnel, sans corps (§15.4.5), et le cache réutilise celui qu’il a conservé ; sinon, dans ce parcours normal, il renvoie la représentation actuelle. L’étiquette suit la représentation, pas seulement la commande : une représentation modifiée sans que la commande change peut exiger une autre étiquette.
Reste le lien suivi, que l’application suit au lieu de construire l’adresse de l’expédition. Ni JSON seul ni le simple emploi de GET ne décrivent ces comportements.
Le navigateur est un client générique : il dialogue avec des serveurs qu’il n’a jamais rencontrés, sans être recompilé pour aucun d’eux. C’est possible parce que chaque réponse lui indique ce qu’il peut faire ensuite : les liens à suivre, les formulaires à soumettre. Ces liens et ces formulaires présents dans les réponses forment l’hypermédia.
Les rôles se répartissent ainsi : le navigateur sait afficher une page et soumettre un formulaire ; la personne qui l’utilise choisit l’action qui correspond à son objectif ; le serveur fournit les destinations et les contrôles disponibles. Fielding décrit l’application REST type comme un moteur qui passe d’un état à l’autre en examinant les transitions proposées par les représentations reçues, puis en choisissant parmi elles, et il note que cela correspond exactement à l’interface d’un navigateur hypermédia (§5.3.3).
Un client qui construit toutes ses destinations à partir de chemins enregistrés dans son code reste dépendant de ces chemins : si le serveur déplace le suivi d’expédition, ce client ne le trouve plus. Cette pratique existe dans des API appelées « REST », mais elle ne définit pas le style REST. L’hypermédia réduit cette dépendance sans supprimer tout contrat : le client doit encore comprendre le format des messages et le sens des relations qu’il utilise, comme « suivi ».
Le modèle de maturité que Leonard Richardson a présenté en 2008, et que Martin Fowler a décrit en 2010, donne un vocabulaire pour situer une API. Au-dessus d’un simple point d’entrée, il distingue trois niveaux : des ressources identifiées, l’emploi des méthodes HTTP selon leur sens, puis les contrôles hypermédia. Fowler précise que ce modèle n’est pas une définition de niveaux de REST, et que Fielding tient le troisième niveau pour une condition préalable de REST. Une API qui renvoie C-42 en JSON avec des méthodes bien choisies, mais sans aucun lien, s’arrête au deuxième. Fielding ouvre d’ailleurs son billet de 2008 sur une API HTTP présentée comme REST, qu’il qualifie de RPC.
Le JSON et les verbes d’une API ne suffisent donc pas à la qualifier de REST. Lisez plutôt une réponse réelle, comme celle de C-42, et vérifiez séparément chaque propriété : le cache respecte-t-il les directives reçues, le client suit-il les liens au lieu de construire les adresses, une requête se comprend-elle sans conversation mémorisée sur un serveur particulier ? Une capture ne certifie pas toute une architecture, puisque le comportement du client n’y figure pas. Elle montre les contrats à examiner et les contre-exemples à tester. Une API de deuxième niveau peut très bien suffire, par exemple quand la même équipe livre le client et le serveur ; ne l’appelez simplement pas REST.
La réponse minimale du début ne rendait explicites ni le contrat de cache choisi ni une transition vers le suivi. La réponse enrichie dit à un cache ce qu’il peut garder et à un client où aller ensuite, en laissant au serveur la maîtrise de ses adresses : elle montre ce que REST demande en plus de HTTP et de JSON, sans prouver que le reste de l’architecture le respecte. L’article sur l’interface uniforme et l’hypermédia suit un client guidé de cette façon jusqu’au paiement d’une commande.
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.
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.
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é.