Documentation API obsolète : tester les actions des agents en toute sécurité

Une documentation API obsolète est un problème de sécurité pour les agents, pas un simple désagrément éditorial. Une personne peut lire un exemple dépassé, hésiter, puis demander conseil à un collègue. Un agent de programmation autonome transformera souvent ce même exemple en requête, puis prendra la réponse comme preuve qu'il a agi correctement.

Cette différence change le niveau d'exigence. Si votre documentation apprend à un agent à appeler une API, à renouveler un jeton, à supprimer un enregistrement ou à atteindre un hôte de production, considérez le texte comme une entrée exécutable. Testez-le en même temps que l'outil. Une page exacte au moment de sa publication, mais qui ne correspond plus au service en production, peut pousser un agent à effectuer une action dangereuse alors même que l'API fonctionne exactement comme ses responsables actuels le souhaitent.

La dérive la plus dangereuse ne provoque presque jamais un échec évident. Une erreur 404 attire l'attention. Une requête qui renvoie toujours 200 tout en sélectionnant davantage de ressources, en appliquant une valeur par défaut différente ou en contournant une confirmation attendue passe inaperçue. C'est le genre de décalage qui produit un journal d'activité impeccable et une très mauvaise journée.

La documentation fait partie du plan de contrôle de l'agent

Un agent utilise la documentation pour choisir des opérations, remplir des paramètres, interpréter des réponses et décider s'il doit réessayer. Les exemples, tableaux de référence, guides d'authentification et notes de migration font donc partie de son plan de contrôle. Le code du service peut être correct alors que ce plan indique à l'agent une mauvaise manière de l'utiliser.

Les équipes établissent souvent une séparation artificielle entre la définition d'un outil et un guide. Une définition d'outil indique deleteProject(project_id). Le guide précise quel identifiant de projet récupérer, s'il existe un mode simulation, si la suppression est en cascade et quoi faire après un échec d'autorisation. L'agent a besoin des deux. Si l'un des deux ment, l'action obtenue peut être incorrecte.

C'est pourquoi un exemple obsolète ne se résume pas à un paragraphe mal orthographié. Imaginez une ancienne instruction indiquant qu'un paramètre scope absent signifie « projet courant ». Après une modification du backend, la même omission signifie « tous les projets accessibles à cet identifiant ». L'endpoint fonctionne toujours. L'exemple est toujours valide syntaxiquement. Un agent qui suit l'ancien guide peut désormais appliquer une modification supposée locale à l'ensemble d'un compte.

La documentation définit aussi le niveau de confiance de l'agent. Les extraits concrets pèsent davantage qu'un avertissement vague dans le texte voisin. Si une page dit « appliquez le principe du moindre privilège » et qu'une autre fournit un exemple de jeton bearer avec un accès à tout le compte, c'est l'extrait qui l'emporte en pratique. Les agents cherchent le chemin qui produit un résultat.

Considérez les éléments suivants comme une documentation porteuse d'actions :

• Exemples de requêtes et de commandes
• Tableaux de paramètres décrivant les valeurs par défaut et les valeurs autorisées
• Instructions de configuration de l'authentification, des identifiants et de l'environnement
• Conseils sur les nouvelles tentatives, la pagination, l'idempotence et la gestion des erreurs
• Instructions de migration et de dépréciation indiquant quelle opération en remplace une autre

Il est utile de distinguer la dérive syntaxique de la dérive sémantique. La première fait échouer un exemple parce qu'un champ ou un chemin a changé. La seconde laisse l'exemple valide, mais modifie ce qu'il affecte. La dérive syntaxique embarrasse son auteur. La dérive sémantique peut endommager des données, dépenser de l'argent, exposer des enregistrements ou élargir les accès. Votre suite de tests doit détecter les deux.

Une requête réussie peut quand même prouver que l'exemple est faux

Un test documentaire qui vérifie uniquement les codes de statut détecte les échecs faciles et laisse passer les problèmes dangereux. Une réponse HTTP réussie signifie que le serveur a accepté la requête. Elle ne dit rien sur le fait qu'elle visait le bon objet, produisait l'effet décrit ou respectait la limite annoncée.

Supposons qu'une page de référence publie cette requête :

curl -sS -X POST "$API_URL/v1/exports" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project":"demo","include_archived":false}'

Un test élémentaire vérifie la réponse 202 Accepted et conclut que tout va bien. Il ne détecte pas plusieurs changements importants :

• Le service renomme silencieusement project en project_id et considère l'ancien champ comme absent.
• include_archived passe d'une option d'exclusion à un champ de compatibilité ignoré.
• L'identifiant acquiert une visibilité sur tout le compte, et demo correspond alors au projet d'un autre tenant.
• L'endpoint met toujours le travail en file, mais exporte désormais les pièces jointes que le guide dit exclure.

Le test doit examiner le résultat et l'état du service, pas seulement le statut. Dans un compte jetable, créez un enregistrement actif et un enregistrement archivé. Envoyez la requête documentée. Interrogez le job obtenu. Vérifiez que l'artefact contient l'enregistrement actif, exclut l'enregistrement archivé et contient l'identifiant de projet attendu. Si le service ne peut pas fournir suffisamment d'éléments pour cette vérification, la documentation ne peut pas non plus garantir ce comportement en toute sécurité.

La RFC 9110 définit les codes de statut HTTP comme le résultat du traitement d'une requête. Elle ne prétend pas qu'un statut réussi prouve l'intention métier de l'appelant. Cela paraît évident, mais les équipes continuent de créer des contrôles documentaires qui réduisent le protocole à curl plus grep 200. Utilisez la sémantique HTTP pour les assertions de protocole, puis ajoutez des assertions sur le résultat réel.

Un bon test nomme l'affirmation qu'il vérifie. export_excludes_archived_records est utile. docs_example_returns_success indique surtout que quelqu'un a envoyé une requête.

Les exemples ont besoin de tests de contrat, pas d'une revue de captures d'écran

Copier un exemple depuis une page de documentation dans un terminal pendant la revue d'une version vaut mieux que rien. Cette pratique ne passe pas à l'échelle, ne laisse aucune preuve fiable et privilégie le cas nominal. Les personnes corrigent aussi souvent la commande localement sans corriger la page.

Placez les exemples exécutables dans un fichier source structuré, générez l'extrait affiché à partir de cette source et exécutez cette même source dans la CI. Vous pouvez utiliser les exemples OpenAPI, l'extraction de code Markdown ou un répertoire séparé de fixtures. Le mécanisme importe moins qu'une propriété : la commande visible par le lecteur doit être celle exécutée par le test.

Ne maintenez pas discrètement une « version de test » avec des URL plus sûres, des portées plus étroites ou des en-têtes plus complets que l'exemple publié. Cette séparation crée une compilation verte rassurante pendant que les instructions publiques se dégradent. Paramétrez uniquement les valeurs qui doivent différer selon l'environnement, comme l'URL de base, les identifiants de test et les identifiants de fixtures. Gardez identiques la méthode, le chemin, la structure du corps et les options de sécurité importantes.

Un petit test shell peut illustrer le principe :

set -euo pipefail

project_id="docs-check-$RANDOM"
response=$(curl -sS -X POST "$API_URL/v1/projects" \
  -H "Authorization: Bearer $DOCS_TEST_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"id\":\"$project_id\",\"name\":\"Documentation check\"}")

printf '%s' "$response" | jq -e \
  --arg id "$project_id" \
  '.id == $id and .name == "Documentation check" and .archived == false'

La sortie attendue de jq -e est la valeur JSON true, et une différence provoque une sortie avec un code non nul. L'important n'est pas la syntaxe shell. L'assertion encode ce que le texte affirme : l'API crée un projet avec l'identifiant fourni, conserve le nom fourni et ne l'archive pas par défaut.

Créez un contrôle distinct pour la documentation rendue. Si un extracteur Markdown récupère sur la page un bloc marqué bash, le test doit exécuter ce bloc après substitution des variables d'environnement approuvées. Si vous générez la documentation à partir d'une description OpenAPI, testez l'exemple généré plutôt qu'une copie manuelle. Une revue de capture d'écran peut encore servir à vérifier la lisibilité. Elle ne peut pas prouver le comportement. Un relecteur oubliera étonnamment souvent un en-tête manquant, surtout lorsque la page contient plusieurs exemples similaires. Les machines ne se lassent pas de comparer un champ à une fixture.

Les contrôles du service en production doivent couvrir les valeurs par défaut et les chemins d'échec

La plupart des changements d'API les plus dangereux concernent les valeurs par défaut, les limites d'autorisation et la gestion des échecs. Les tests du cas nominal évitent les trois, car ils sont faciles à écrire et à maintenir au vert.

Testez les cas où un champ est omis, comme pourrait le faire un agent. Les agents construisent souvent les payloads conditionnellement : un champ facultatif peut disparaître lorsqu'une recherche précédente ne renvoie aucune valeur. Pour chaque paramètre facultatif documenté, déterminez si son omission est sûre, rejetée ou sémantiquement différente. Testez ensuite directement le comportement documenté.

Pour une opération qui possède un champ dry_run, exécutez au moins les cas suivants dans un environnement isolé :

1. dry_run: true renvoie un plan et ne modifie pas la fixture.
2. dry_run: false effectue le changement indiqué uniquement sur la fixture nommée.
3. L'omission de dry_run rejette la requête ou applique la valeur par défaut documentée.
4. Un jeton dont la portée est insuffisante échoue avant toute modification.
5. La répétition de la requête documentée se comporte comme l'indiquent les conseils d'idempotence.

Le troisième cas détecte une cause fréquente de dommages accidentels. Une équipe modifie une valeur par défaut pour favoriser les utilisateurs interactifs, tandis que la documentation suppose encore l'ancienne valeur. Une interface humaine peut afficher une confirmation. Un client API n'en a pas.

Les exemples d'échec ont eux aussi besoin de tests. La documentation dit souvent « réessayez en cas de 429 » sans préciser si la réponse contient Retry-After, si l'opération peut être répétée sans danger ou si la requête doit contenir un jeton d'idempotence. Ce conseil peut transformer une brève limitation de débit en factures, déploiements ou révocations en double.

Testez exactement les instructions d'échec. Provoquez la limitation dans un service de test ou un environnement contrôlé. Vérifiez que le client documenté lit l'en-tête indiqué, attend le délai prévu et renvoie le même identifiant d'idempotence lorsque l'API en prend un en charge. Si le service ne peut pas produire l'erreur de manière prévisible, documentez cette incertitude au lieu de publier une recette trop affirmative.

Le mot-clé default d'OpenAPI crée un piège similaire. Dans les descriptions JSON Schema et OpenAPI, une valeur par défaut déclarée indique généralement ce que les outils peuvent supposer ou afficher. Elle n'oblige pas automatiquement tous les serveurs à appliquer cette valeur. Vérifiez le service déployé avec un champ omis. Une valeur par défaut du schéma et une valeur par défaut du serveur sont deux affirmations distinctes tant qu'un test ne les relie pas.

Les workflows destructifs exigent des preuves jetables

Ne testez pas des exemples destructifs sur un compte de staging partagé en prétendant que c'est sûr. Les environnements partagés accumulent d'anciennes fixtures, des essais manuels et des identifiants dont la portée est incertaine. Un test documentaire finira par cibler le mauvais objet, ou une commande de nettoyage dépassera sa limite prévue.

Utilisez un tenant ou un compte de test dédié, avec des identifiants qui ne peuvent atteindre que les ressources de test. Créez chaque fixture avec un marqueur d'exécution unique. Récupérez-la avec ce marqueur avant toute modification. Après le test, vérifiez l'état obtenu au lieu de supposer que l'API a fait ce que la réponse indiquait.

Un exemple de suppression doit démontrer tout le cycle de vie :

create fixture: docs-delete-<run-id>
read fixture: confirm owner=test-suite and run_id=<run-id>
delete fixture: send the rendered documentation request
read fixture: expect the documented absence or tombstone state
list nearby fixtures: confirm unrelated fixtures remain

Cette dernière vérification est importante. Un test de suppression qui confirme seulement la disparition de l'objet choisi ne détectera pas un sélecteur trop large. J'ai vu des équipes accepter un endpoint de suppression groupée parce que leur unique fixture avait disparu comme prévu, alors que l'endpoint avait aussi supprimé toutes les ressources portant un préfixe similaire. Le test avait besoin d'un voisin volontairement similaire qui devait rester intact.

Ne demandez pas aux agents d'utiliser des sélecteurs pratiques comme latest, all, un filtre vide ou un nom lisible par un humain lorsqu'un identifiant immuable existe. Ces sélecteurs semblent pratiques dans un tutoriel et deviennent dangereux lorsqu'un agent exécute la recette dans un compte actif. Si une opération exige réellement un sélecteur large, placez la portée dans le corps de la requête ou dans les arguments de la commande, là où un relecteur peut la voir. Ne la cachez pas dans une valeur par défaut du serveur.

Pour les opérations irréversibles, publiez une lecture préalable et faites utiliser son résultat par l'exemple. Récupérez d'abord l'objet, vérifiez son ID immuable et son état pertinent, puis envoyez la modification. Cela ajoute une friction. Cette friction coûte moins cher que d'expliquer pourquoi un agent a supprimé l'objet qui partageait par hasard le même nom d'affichage.

Les tests d'outils doivent comparer le sens, pas seulement les schémas

La validation du schéma est nécessaire, mais les schémas décrivent généralement la forme plus fidèlement que les conséquences. Un corps de requête peut respecter toutes les contraintes de type tout en dirigeant une action vers le mauvais environnement ou avec des privilèges inadaptés.

Construisez vos assertions autour de quatre questions : qui l'action a-t-elle affecté ? Quel état a changé ? Quel état n'a pas changé ? Quelle identité l'a autorisée ? Ces questions conviennent aux API HTTP, aux commandes SSH et aux outils internes.

Pour HTTP, capturez l'identifiant de requête lorsque le service en fournit un, puis interrogez la ressource obtenue ou l'enregistrement d'audit dans l'environnement de test. Faites correspondre l'identifiant de requête, l'acteur, la cible et la modification. Pour SSH, exécutez les commandes sur un hôte jetable, capturez le code de sortie et la sortie, puis inspectez l'état de l'hôte avec une commande de vérification distincte. Ne demandez pas à la commande d'action de corriger son propre devoir.

Une bonne fixture offre un contraste. Si vous testez une commande qui doit redémarrer un service, créez un autre service qui doit rester actif. Si vous testez une requête limitée à un dépôt, ajoutez un second dépôt visible par le même identifiant, mais que la requête ne doit pas toucher. Sans contraste, une action trop large peut sembler correcte.

C'est là que de nombreuses équipes utilisent mal les tests de contrat. Les outils de contrat pilotés par le consommateur peuvent confirmer qu'un fournisseur accepte une forme de requête et renvoie les champs attendus. Ils ne peuvent pas déterminer si la requête a sélectionné le bon compte de production, si l'option force a pris un nouveau sens ou si une suppression s'est propagée au-delà de l'objet documenté. Conservez le test de contrat. Ajoutez un test de résultat avec des fixtures conçues pour révéler une portée excessive.

La description d'un outil doit également être testée. Si un outil expose environment, ne décrivez pas production comme une valeur acceptable sans vérifier qu'elle dirige vers l'hôte documenté et utilise le chemin d'autorisation indiqué. Les agents utilisent les descriptions pour remplir les arguments. Une description obsolète n'est qu'une version en prose d'un exemple API obsolète.

Un agent a besoin de preuves de fraîcheur et d'une voie de refus sûre

Un agent ne doit pas déduire que la documentation est à jour parce qu'elle se trouve dans un dépôt ou un portail interne. Donnez-lui des preuves de vérification lisibles par machine et liées à l'opération qu'il prévoit d'appeler.

Un manifeste simple peut suffire :

{
  "operation": "POST /v1/exports",
  "documentation_source": "docs/api/exports.md#creating-an-export",
  "verified_in": "isolated-test-tenant",
  "verification_commit": "<commit-id>",
  "assertions": [
    "returns an export job",
    "omits archived fixtures when include_archived is false",
    "rejects a token without export scope"
  ],
  "review_required_when": ["production", "include_archived=true"]
}

L'identifiant de commit n'est pas une preuve de confiance à lui seul. Il permet au relecteur de retrouver la source documentaire et le code de test qui ont produit ces éléments. Enregistrez l'heure de vérification dans vos propres artefacts de build si votre processus exige une limite d'âge, mais ne prétendez pas qu'un horodatage rend un ancien comportement sûr. Un déploiement du service peut invalider le test d'hier.

La règle de décision de l'agent doit être simple. Si l'opération demandée ne possède pas de résultat de vérification valide pour l'interface déployée, l'agent doit soit effectuer une pré-vérification non mutante dans un contexte de test approuvé, soit demander à une personne d'approuver l'action exacte. Il ne doit pas improviser à partir d'un endpoint voisin.

Séparez « inconnu » de « sûr ». Les agents ont tendance à combler les lacunes, car la réalisation d'une tâche produit un retour positif. La conception de l'outil doit faire de l'abstention un résultat acceptable lorsque les preuves manquent. Retournez une raison comme : documentation example has no verified outcome test for this operation. Ce message fournit au développeur une cible de correction plutôt qu'un refus vague.

Ne tentez pas de résoudre ce problème avec un long fichier de règles qui essaie d'énumérer toutes les formulations risquées dans chaque document. Les mots changeront plus vite que les règles. Reliez une opération concrète à un test concret et transmettez le résultat à l'agent.

Les portes de publication ne fonctionnent que si elles bloquent la page trompeuse

Un programme de vérification documentaire échoue lorsqu'il produit des rapports auxquels personne n'est tenu de donner suite. Le contrôle doit bloquer la publication, ou au moins l'accès de l'agent à l'exemple concerné, lorsque le contrat du service change.

Reliez les contrôles aux modifications de la spécification API, des gestionnaires de routes, des middlewares d'authentification, des générateurs de requêtes du SDK et des sources documentaires. Une modification de l'un de ces éléments doit exécuter les tests des exemples concernés. En cas d'échec, l'équipe a trois choix honnêtes : rétablir l'ancien comportement, mettre à jour la documentation et les tests pour le nouveau comportement, ou rendre l'opération indisponible aux agents jusqu'à la réussite de la vérification.

La revue manuelle reste utile pour exercer son jugement, mais elle ne suffit pas. Elle est populaire parce qu'elle semble peu coûteuse et préserve une publication rapide. Elle demande aussi au relecteur de simuler mentalement un service, des identifiants, des valeurs par défaut et des transitions d'état à partir du texte. Les personnes ne peuvent pas le faire de manière fiable à chaque version courante.

Rendez les échecs compréhensibles. Un rapport utile indique la page, le bloc de code, l'opération, la fixture, la réponse observée et l'assertion non respectée. « L'intégration de la documentation a échoué » déclenche une chasse au trésor. « exports.md, ligne 42, indique que les enregistrements archivés sont exclus ; l'artefact d'export contient la fixture archived-run-817 » donne à son responsable une correction directe.

Ne relâchez pas un test simplement parce qu'une modification du service le rend gênant. Déterminez d'abord si l'ancienne promesse était utile. Si oui, restaurez-la ou exposez clairement la nouvelle limite. Si elle était dangereuse, supprimez l'exemple au lieu de le conserver avec une formulation plus douce. Un agent suivra généralement la commande qui reste.

La documentation versionnée exige la même discipline. Une page consacrée à une ancienne version de l'API peut décrire correctement un ancien déploiement tout en induisant en erreur un agent dirigé vers l'URL de base actuelle. Placez la version dans le chemin de l'endpoint, l'URL du serveur ou les métadonnées de l'outil afin que l'agent puisse la lier à la requête. Un titre « v1 » placé quelque part en haut de la page constitue une preuve faible.

Les limites d'autorisation réduisent l'impact, mais ne corrigent pas les mauvaises instructions

Les approbations et l'isolation des identifiants restent importantes, car les contrôles documentaires laisseront passer certains défauts. Elles réduisent les dégâts lorsqu'un agent choisit la mauvaise opération. Elles ne transforment pas une instruction obsolète en instruction correcte.

Séparez les deux responsabilités. La vérification documentaire demande : « Cet exemple décrit-il le service en production et ses conséquences ? » L'autorisation d'action demande : « Cet agent doit-il pouvoir effectuer cet appel maintenant ? » Les mélanger crée de la confusion. Un utilisateur peut approuver un appel parce que l'agent affirme qu'il exportera un seul projet, alors que l'exemple obsolète exporte en réalité tous les projets accessibles à l'identifiant.

Pour les actions HTTP et SSH pilotées par un agent, Sallyport garde les identifiants hors de portée de l'agent et peut demander à une personne d'autoriser une session ou l'utilisation d'un identifiant particulier. C'est une dernière limite utile lorsqu'un contrôle documentaire ne fournit aucune preuve fiable ou lorsqu'une action a des conséquences qui méritent un examen humain.

L'écran d'approbation doit afficher l'opération, la cible et la portée avec des termes qu'une personne peut évaluer. « POST /v1/exports » ne suffit pas lorsque le corps contient include_archived=true ou un sélecteur couvrant tout le compte. Si votre couche d'autorisation ne peut pas révéler la portée réelle, réduisez l'interface de l'outil jusqu'à ce qu'elle le puisse.

Les journaux d'audit fournissent ensuite le matériau nécessaire à l'amélioration des tests. Lorsqu'une personne révoque une exécution ou remet une action en question, examinez la requête exacte, la source documentaire citée par l'agent et les preuves de vérification dont il disposait. Ne voyez pas cet examen comme une recherche de coupable. Utilisez-le pour ajouter la fixture, l'assertion ou la condition de refus manquante.

Commencez par tester l'exemple qui risque le plus de vous faire regretter votre décision

Ne commencez pas par la requête GET la plus propre de la référence. Commencez par l'exemple qui peut supprimer, publier, renouveler, accorder, facturer ou atteindre un hôte de production. Donnez-lui une fixture isolée, exécutez la commande rendue exacte et vérifiez le changement attendu ainsi que le changement voisin qui ne doit pas se produire.

Reliez ensuite ce test à la source documentaire et rendez l'échec visible avant la publication ou l'utilisation par un agent. Ce travail est moins séduisant que la rédaction d'une nouvelle description d'outil, mais il élimine une hypothèse dangereuse : une page serait sûre parce qu'elle a été relue un jour.

Un service en production change. Sa documentation changera plus lentement si vous ne les forcez pas à se retrouver dans un test. Faites de cette rencontre une étape de la publication, avant qu'un agent ne transforme une ancienne phrase en action.