Connecter un agent à une API : hypermédia ou MCP ?
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.
Article
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.
Vous filtrez une liste de factures. Le navigateur peut recevoir des données JSON puis construire les lignes lui-même, ou recevoir du serveur le fragment HTML prêt à afficher. htmx facilite la seconde approche, et c’est celle à retenir pour cet écran : le serveur garde la validation, les liens et la présentation, et le code côté navigateur se réduit, pour le remplacement des résultats, à quelques attributs. Elle ne remplace pas une API de données pour les programmes, ni l’état local d’une interface qui doit fonctionner sans réseau.
Pour choisir, il faut suivre l’échange jusqu’au résultat : un formulaire ordinaire, le même avec htmx, une saisie invalide et une coupure réseau, l’URL et l’historique, et enfin les autres consommateurs des mêmes données.
Dans cet exemple fictif, l’écran contient une recherche par montant minimal. Avec un formulaire HTML ordinaire, la soumission ouvre une nouvelle page de résultats. Le serveur lit minimum, valide sa valeur, recherche les factures auxquelles l’utilisateur a accès et produit la page. L’URL conserve le filtre ; elle peut être partagée ou rechargée.
<form action="/factures" method="get">
<label for="minimum">Montant minimal en euros</label>
<input id="minimum" name="minimum" type="number"
min="0" step="1" value="100">
<button type="submit">Filtrer</button>
</form>
Ce formulaire est déjà de l’hypermédia : la page envoyée par le serveur contient, en plus de son texte, les contrôles qui permettent d’aller plus loin, ici l’adresse à appeler, la méthode et le champ à remplir. Le navigateur sait soumettre un formulaire sans rien connaître de la facturation. L’article sur l’interface uniforme et l’hypermédia détaille ce principe pour les API.
La requête correspondante est GET /factures?minimum=100. Le contrôle du navigateur (min="0") améliore la saisie, mais ne protège pas le service : une requête fabriquée à la main peut envoyer minimum=abc. Le serveur doit la traiter explicitement, et le choix du rendu ne change rien à cette responsabilité.
Recharger toute la page à chaque filtre fonctionne, mais redessine aussi l’en-tête, le menu et le formulaire. htmx est une bibliothèque JavaScript qui évite ce rechargement : des attributs ajoutés au HTML déclenchent des requêtes HTTP et insèrent dans la page le HTML reçu. Les extraits suivants ciblent htmx 2.0.4, chargé par la page. Cette version sert de référence reproductible à l’exemple, pas de recommandation de version pour une nouvelle application. Le formulaire reçoit quelques attributs supplémentaires :
<form action="/factures" method="get"
hx-get="/factures"
hx-target="#resultats"
hx-select="#resultats"
hx-swap="outerHTML"
hx-push-url="true">
<label for="minimum">Montant minimal en euros</label>
<input id="minimum" name="minimum" type="number"
min="0" step="1" value="100">
<button type="submit">Filtrer</button>
</form>
<section id="resultats" aria-live="polite">
<p>Choisissez un montant, puis filtrez les factures.</p>
</section>
hx-get déclenche la requête à la soumission. hx-target désigne la zone à remplacer ; hx-select sélectionne cette même zone dans la réponse ; outerHTML remplace l’élément entier. Le serveur peut donc continuer à retourner une page HTML complète : htmx n’en prélève que #resultats. La documentation de htmx décrit cette sélection dans une réponse. Les attributs action et method restent en place : sans JavaScript, le formulaire se comporte comme dans la section précédente.
Pour 100 €, supposons deux factures autorisées : F-104 à 120 € et F-109 à 240 €. La réponse complète contient notamment :
<section id="resultats" aria-live="polite">
<p>2 factures d’au moins 100 €</p>
<ul>
<li><a href="/factures/F-104">F-104 — 120 €</a></li>
<li><a href="/factures/F-109">F-109 — 240 €</a></li>
</ul>
</section>
Le navigateur affiche les liens reçus. Il n’a pas reconstruit la liste à partir d’un tableau JSON ni fabriqué l’adresse de détail à partir du numéro de facture. Pour ajouter un libellé « échue » à F-104, le serveur change son gabarit, et aucun code du navigateur ne change. Un clic suit ensuite un lien HTML ordinaire : le choix d’actualiser partiellement le filtre n’impose pas de convertir toute la navigation.
Le champ numérique du navigateur refuse normalement une valeur négative ou illisible, mais une requête fabriquée à la main, ou un contrôle contourné, peut quand même en envoyer une. Le serveur renvoie alors une page avec un message dans la même zone et le statut 400. L’exemple emploie 400 plutôt que 422, que vous rencontrerez souvent pour les erreurs de validation : la RFC 9110 réserve 422 à un contenu de requête bien formé mais impossible à traiter (§15.5.21). Or cette requête GET n’a pas de contenu, et l’erreur est dans l’adresse ; 400 désigne une erreur du client en général (§15.5.1).
Par défaut, htmx 2 ne remplace pas la cible avec le corps des réponses 4xx. Sans configuration, l’utilisateur garderait donc sous les yeux les résultats précédents, sans comprendre que sa nouvelle recherche a échoué. Ce comportement est documenté dans la gestion des réponses. Dans la page de l’exemple, la configuration suivante autorise uniquement ce statut de validation en plus des réponses ordinaires. Elle ne demande pas d’afficher toutes les erreurs serveur comme si elles étaient des résultats :
<meta name="htmx-config" content='{
"responseHandling": [
{"code":"204", "swap":false},
{"code":"[23]..", "swap":true},
{"code":"400", "swap":true, "error":false},
{"code":"[45]..", "swap":false, "error":true},
{"code":"...", "swap":false}
]
}'>
Les règles s’appliquent dans l’ordre : le 400 est traité avant la règle générale des 4xx et 5xx. Le fragment sélectionné dans la page de validation indique alors : « Le montant minimal doit être un entier positif ou nul. Aucun nouveau résultat n’a été calculé. » Le service n’exécute pas silencieusement une recherche sans filtre. La même page complète reste lisible lorsque JavaScript est désactivé. Cette règle suppose que toute réponse 400 de cette route est une page de validation qui contient #resultats ; une erreur 400 venue d’un intermédiaire ou d’une autre route ne devient pas un message de validation par son seul statut.
Une coupure réseau demande un autre traitement, puisqu’aucune page de validation n’arrive. L’interface doit signaler l’échec de la requête, conserver la saisie et permettre une reprise. Si les anciens résultats restent affichés, leur ancienneté doit être explicite. htmx émet l’événement htmx:sendError en cas d’erreur de connexion, et htmx:responseError pour une réponse d’erreur ; ils permettent de raccorder ce comportement, mais htmx ne peut pas deviner le message adapté à votre métier, et les extraits de cet article ne contiennent pas ces gestionnaires.
hx-push-url inscrit le filtre dans l’historique du navigateur. Ouvrir directement cette URL doit donc produire une page entière, pas une poignée de lignes sans formulaire. Le choix de l’exemple, retourner toujours la page complète, rend ce cas simple et évite deux représentations différentes pour la même requête. Le prix est de transférer un peu de HTML que htmx écarte.
Une autre réalisation renverrait seulement le fragment lorsque l’en-tête HX-Request, que htmx ajoute à ses requêtes, est présent. Elle doit alors traiter la restauration de l’historique : quand htmx ne trouve pas une page dans sa copie locale, il la redemande au serveur avec l’en-tête HX-History-Restore-Request et attend la page entière (documentation de htmx). Dans le code de htmx 2.0.4, cette requête porte aussi HX-Request : le serveur doit donc donner la priorité au second en-tête. Le cache HTTP doit enfin distinguer les variantes. La documentation de htmx demande Vary: HX-Request, et la restauration impose d’y ajouter le second en-tête : Vary: HX-Request, HX-History-Restore-Request. Sinon, un cache peut servir le fragment à une navigation qui attend la page entière. Commencez par la réponse complète, puis réduisez le transfert si un besoin mesuré le justifie.
Les factures sont personnelles : les exemples ne supposent aucun cache partagé autorisé à les redistribuer, et la politique d’accès et de stockage des réponses doit être conçue pour ces données. htmx conserve en outre, pour l’historique, une copie de la page dans le localStorage du navigateur. L’attribut hx-history="false" l’en empêche pour une page sensible ; htmx redemande alors l’URL au serveur quand l’utilisateur revient en arrière. Cacher un lien dans le HTML ne remplace pas non plus la vérification des droits lorsque le détail de F-104 est demandé.
Cette restauration depuis le serveur pose un dernier cas : la recherche invalide. Avec la règle de la section précédente, htmx affiche la page 400 et inscrit aussi son URL dans l’historique. Or, dans le code de htmx 2.0.4, la restauration suit un autre chemin que l’échange ordinaire : elle n’accepte que les statuts 200 à 399, sans consulter responseHandling, et signale sinon l’événement htmx:historyCacheMissLoadError. Une recherche invalide inscrite dans l’historique ne pourrait donc pas être restaurée sans copie locale. Le serveur ajoute pour cela l’en-tête de réponse HX-Push-Url: false à sa page 400, qui empêche htmx d’inscrire cette recherche ; une navigation directe vers la même URL reçoit toujours la page complète.
Hypermedia Systems, de Carson Gross, Adam Stepinski et Deniz Akşimşek, développe cette approche en construisant une application de contacts. Le livre distingue les interfaces hypermédia destinées aux utilisateurs des API de données destinées aux programmes. Cette distinction permet de faire évoluer une interface sans imposer chaque changement de présentation aux intégrations.
Dans l’exemple, un comptable veut filtrer puis ouvrir une facture. Un logiciel de comptabilité peut vouloir toutes les factures modifiées depuis hier, avec une pagination stable et des montants dans un format précis. Lui faire analyser les libellés « 120 € » du fragment HTML ajouterait un contrat fragile : il lui faut un format de données documenté. Le livre en tire une conclusion nette : ses auteurs placent l’API de données sur ses propres adresses, parce que les deux usages évoluent à des rythmes différents, et jugent que leur expérience de la négociation de contenu sur les mêmes adresses « has not been great ».
L’exemple retient pourtant l’autre voie : la liste des factures reste une seule ressource, que le navigateur demande en HTML et le logiciel de comptabilité en JSON, par l’en-tête Accept, comme le montre le schéma. Les paramètres de sélection restent explicites dans l’adresse : pour une même sélection et les mêmes droits, l’en-tête choisit seulement la représentation, et le filtre par date de modification comme les garanties de pagination font partie du contrat de cette liste. Les deux représentations se complètent : elles portent les mêmes factures et les mêmes opérations, chacune sous la forme que son lecteur sait traiter, et aucune adresse parallèle n’est à tenir d’accord avec la première. La stabilité que demande le logiciel ne tient pas à l’adresse, mais au contrat de la représentation JSON : ses champs, son format de montant et sa pagination sont documentés et ne changent pas quand la présentation HTML change. Un cache doit alors distinguer aussi cet en-tête, par Vary: Accept, à combiner avec les variantes propres à htmx. La négociation de contenu se comprend mieux comme une fondation de ce style d’architecture, utile à l’interface comme aux programmes, que comme une commodité réservée aux clients machine. L’objection du livre en fixe la condition : servir deux représentations depuis le même code demande de séparer nettement la production des données de leur mise en forme, faute de quoi chaque changement d’écran risque de toucher le contrat JSON.
Une interface de dessin ou un éditeur hors ligne pose une autre limite : il doit conserver beaucoup d’état local et réagir sans attendre le serveur. Le filtre de factures explique pourquoi le rendu serveur peut réduire le code de présentation ; il ne démontre pas qu’un aller-retour réseau convient à chaque interaction.
Pour l’écran du début, le filtre renvoie donc du HTML : le serveur valide le montant, produit les liens de détail et annonce l’erreur dans la zone de résultats, tandis que le navigateur se contente de remplacer cette zone. Le logiciel de comptabilité reçoit la représentation JSON documentée de la même ressource. Si un jour l’écran doit fonctionner sans réseau, c’est l’état local qui décidera, plus que le format des réponses.
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.
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.
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.
GET sert souvent les vues de lecture, tandis que les écritures demandent une décision métier. REST et CQRS se combinent sans imposer le même découpage.
Laisser un commentaire
Votre commentaire sera relu avant d'être publié.