Article

Ouvrir une API aux agents : éviter les résultats silencieusement faux

Un filtre ignoré ou une page manquante peut produire un résultat plausible. Comment rendre visibles la sélection, ses limites et la suite du parcours ?

Vous exposez une API, et un agent doit en tirer la liste des commandes urgentes. Si le serveur ignore un filtre mal orthographié, ou s’il masque une panne derrière une liste vide, l’agent peut remettre un rapport faux après des requêtes qui ont toutes réussi. Pour l’éviter, chaque réponse doit permettre au client de savoir ce qu’elle l’autorise à affirmer : quelle sélection a été appliquée, si la liste est complète, et comment poursuivre. Rien de cela n’est propre aux agents : la même API devient plus claire pour tous ses clients.

Depuis la première requête, trois étapes de lecture peuvent fausser ce rapport : le filtre, la pagination et une panne en cours de route. Viennent ensuite une écriture qui prolonge le rapport, puis la recette qui vérifie ces issues.

Un filtre inconnu doit être refusé

L’agent demande GET /commandes?urgnet=true : il a inversé deux lettres d’urgent. Si le serveur ignore ce paramètre qu’il ne connaît pas, il renvoie toutes les commandes, et le client croit que le filtre a été appliqué. Le rapport présente alors comme urgentes des commandes qui ne le sont pas, sans qu’aucune réponse ait signalé d’erreur.

L’API fictive de cet exemple refuse au contraire les paramètres métier inconnus. Le code 400 signale une erreur du client (RFC 9110, §15.5). Le corps de la réponse suit le format Problem Details (RFC 9457) : un objet JSON qui décrit le problème, notamment par un type, un titre et le code de statut, et auquel une API peut ajouter ses propres membres. Ici, parametre et attendu sont des extensions propres à ce contrat ; un client qui ne les connaît pas doit les ignorer et peut toujours lire le type et le titre (§3.2).

GET /commandes?urgnet=true HTTP/1.1

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{"type":"https://api.example/problemes/filtre-inconnu",
 "title":"Filtre inconnu","status":400,
 "parametre":"urgnet","attendu":["urgent","curseur"]}

Le client lit le paramètre fautif et la liste des noms de paramètres acceptés, puis corrige urgnet en urgent. C’est le type d’erreur qu’Anthropic recommande pour les outils d’agents : un message qui indique précisément quoi corriger, plutôt qu’un code opaque (Anthropic, 11 septembre 2025). Le serveur peut aussi éviter la faute en amont. Un compteur de filtre, ou facette, peut porter son lien : « urgent : 3 » devient une sélection que le client suit directement, sans avoir à écrire le nom du paramètre.

Une objection vient alors : HTTP demande aux destinataires d’ignorer les en-têtes inconnus, et aux proxys de les transmettre, sauf configuration contraire. La RFC 9110, §5.1, le prévoit pour que le protocole puisse s’étendre sans mettre à jour tous les intermédiaires déjà déployés. Cette règle porte sur les champs du protocole ; elle ne dit pas comment une application interprète ses paramètres métier. Le refus doit pour autant être défini dans le contrat, paramètre par paramètre. Certains paramètres de suivi ou d’extension peuvent légitimement être ignorés, et refuser soudain ce qui était toléré peut casser des liens existants : un tel changement se prépare comme une évolution du contrat, avec annonce et migration.

La page suivante doit garder la même sélection

Avec le bon filtre, le serveur renvoie la première page des commandes urgentes accessibles à cet utilisateur :

{"selection":{"urgent":true},"instantane":"S42",
 "commandes":[{"id":"C1"},{"id":"C3"}],
 "suivant":"/commandes?urgent=true&curseur=S42-p2"}

selection redit le filtre appliqué, ce qui permet au client de le vérifier. instantane identifie, dans ce contrat fictif, l’état de la sélection au moment de la première page : les pages suivantes portent sur ce même état, même si d’autres commandes deviennent urgentes pendant la lecture. suivant donne l’adresse de la page suivante, construite par le serveur avec le filtre et le curseur.

Le client suit ce lien tel quel, sans recomposer l’adresse lui-même. C’est le principe de l’hypermédia : Roy Fielding décrit l’application cliente comme un moteur qui passe d’un état au suivant en choisissant parmi les transitions présentes dans la représentation reçue (thèse, 2000, §5.3.3). Si le serveur oubliait le filtre en construisant ce lien, la deuxième page porterait sur toutes les commandes, et le client changerait de résultat sans l’avoir demandé.

La deuxième page contient C7 et "suivant": null : sur la dernière page, le serveur n’annonce pas une suite qu’il sait impossible. Le rapport peut maintenant dire « trois commandes urgentes sur l’instantané S42, dans mon périmètre autorisé » ; cette dernière précision rappelle que le serveur ne renvoie que les commandes que cet utilisateur peut voir. Demandée directement, une commande interdite peut même recevoir la réponse 404 d’une ressource inexistante, que la RFC 9110, §15.5.4, autorise pour cacher son existence. Le client ne conclut donc pas qu’il n’existe que trois commandes urgentes dans toute l’entreprise. Ces autorisations passent avant la commodité de l’agent : une API ne révèle pas l’existence d’une ressource interdite pour faciliter son exploration.

Une panne ne doit pas ressembler à une liste vide

Reprenons la lecture à la deuxième page, avec une autre issue : l’index de recherche devient indisponible. Le serveur répond 503 Service Unavailable, qui signale une incapacité temporaire à traiter la demande (RFC 9110, §15.6.4), avec un problème de type « indisponibilité ». Le client conserve C1 et C3 comme résultat partiel et annonce que la recherche n’est pas terminée. Il ne remplace ni l’échec par une liste vide, ni le total inconnu par deux. La reprise dépend de ce que le contrat promet pour S42 : poursuivre le même instantané, ou recommencer sur un nouveau.

Supposons maintenant que le serveur, pour simplifier, réponde à la panne par une liste vide et un code 200. Le client ne peut plus distinguer cette réponse d’une recherche sans correspondance, qui est un résultat valide dans le périmètre effectivement recherché. La liste vide masquerait alors l’échec. Le même soin vaut pour un résultat seulement partiel : une pagination, une limite de volume et une panne d’un service amont sont des situations différentes, et la réponse doit dire ce qui est connu du périmètre manquant. L’article sur les réponses d’une API indisponible ou en retard détaille ce que peut annoncer un mode dégradé.

Le refus du filtre empêche une fausse sélection, le lien de pagination conserve la bonne sélection, et l’erreur explicite empêche une fausse exhaustivité.

Après le rapport, une écriture qui vérifie l’état lu

Le rapport remis, vous demandez à l’agent de confier C3 à l’équipe d’astreinte. Entre la lecture de C3 et cette demande, quelqu’un d’autre a pu modifier la commande. Pour s’en protéger, l’agent lit d’abord C3, et le serveur fournit avec la commande un ETag fort, sans préfixe W/ : un identifiant opaque de la version de la représentation (RFC 9110, §8.8.3). Le client le renvoie tel quel dans l’en-tête If-Match de sa demande de modification. Si un collègue a réaffecté C3 depuis la lecture, la condition est fausse : le serveur n’applique pas l’écriture et peut répondre 412 Precondition Failed. Il applique la comparaison forte, qui exige deux identifiants forts identiques caractère par caractère (§8.8.3.2), et vérifie la condition avant d’exécuter la méthode (RFC 9110, §13.1.1) ; pour qu’aucune autre écriture ne s’intercale, cette vérification et la modification doivent former une seule opération côté serveur. Le client ne reconstruit jamais cet identifiant à partir d’un numéro de version affiché.

Après un refus pour concurrence, relire C3 ne revient pas à autoriser la même modification sur le nouvel état. Si le collègue l’a déjà confiée à une autre équipe, la demande d’origine n’a peut-être plus de sens : l’agent doit la réexaminer, pas seulement remplacer l’ancien identifiant par le nouveau.

Si la modification réussit, prévoyez que le serveur rende la ressource à jour, avec son nouvel ETag et les actions suivantes. Le client prépare alors la suite à partir de l’état confirmé, sans devoir relire la ressource avant chaque écriture. Si le serveur a seulement accepté la demande et la traite encore, sa réponse doit au contraire donner le moyen de suivre le résultat.

Si la connexion se coupe après l’envoi, l’absence de réponse laisse le résultat inconnu : elle ne prouve pas un échec. Une requête est dite idempotente quand la répéter produit le même effet demandé qu’une seule exécution (RFC 9110, §9.2.2). Le contrat d’idempotence et de reprise de l’API doit permettre de décider si le client peut retrouver l’opération, ou la renvoyer sans créer un second effet.

Des erreurs qui disent quoi changer

Les mêmes principes valent pour les autres refus. Une réponse 415 Unsupported Media Type peut indiquer dans son en-tête Accept les formats que la requête aurait pu employer (RFC 9110, §15.5.16), et un corps Problem Details peut expliquer ce qui doit changer. Pour un conflit, indiquez la ressource et le moyen de relire son état. Pour une demande invalide, nommez les champs concernés. Pour une dépendance indisponible, évitez une réponse qui ferait croire à une faute de saisie.

Ces informations doivent venir du contrat réellement appliqué. Si la liste attendu de la première réponse était recopiée à la main dans le code d’erreur et n’était plus à jour, elle proposerait au client un paramètre que le serveur refuse : l’erreur créerait une nouvelle ambiguïté au lieu d’en lever une.

La recette vérifie ce que le client pourra affirmer

Commencez la recette de cette API par les trois issues de lecture. Après la dernière page, le client doit pouvoir annoncer « trois commandes urgentes sur S42, dans mon périmètre autorisé ». Si la deuxième page échoue, il doit pouvoir annoncer « résultat partiel, total inconnu ». Une faute de filtre doit être repérée avant que la liste soit utilisée. Viennent ensuite la poursuite d’une écriture confirmée et le réexamen d’une écriture refusée pour concurrence.

Chaque essai juge ce que le client peut affirmer et faire à partir de la réponse ; le code de statut n’en est qu’un élément. Dans le parcours de C1, C3 et C7, chaque réponse a donné au client les liens et les actions pour continuer, et le serveur est resté responsable du sens et de la validité de ce qu’il exposait. C’est ce partage qui permet à l’agent de remettre un rapport juste, et à n’importe quel autre client de s’appuyer sur les mêmes réponses.

Sources

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é.