Un journal de réponses brutes pour les écritures d'API interrompues

La frontière de l'analyse

Une écriture d'API peut aboutir côté serveur alors que le client ne parvient pas à interpréter la réponse. Un statut HTTP de succès accompagné d'un format JSON inconnu en est un exemple ; une connexion coupée au milieu d'une réponse en est un autre. Aucune de ces deux observations ne prouve, à elle seule, que le serveur a rejeté l'opération. Un client qui jette la réponse et repart de zéro risque de perdre un identifiant d'accès renvoyé ou de rejouer une modification déjà effectuée.

La RFC 9110, section 9.2.2 distingue la sémantique d'idempotence d'une requête du simple nom de la méthode HTTP. Elle déconseille de rejouer automatiquement une requête non idempotente sans disposer d'éléments permettant de savoir que la répétition est sûre ou que la requête initiale n'a pas été appliquée. La procédure ci-dessous propose un enregistrement de preuves côté client pour cet intervalle d'incertitude. Elle ne rend pas un service idempotent.

Enregistrer l'intention avant l'envoi

Attribuez un identifiant d'opération local stable et persistez la destination, la méthode, les en-têtes de requête pertinents et l'empreinte exacte du corps de la requête. Gardez les identifiants d'accès à l'écart des résumés de tâche ordinaires. Rattachez l'opération au compte et à l'entrée validée qui l'autorisent.

L'intention durable doit être validée (commit) avant le début de l'écriture réseau. Au redémarrage, son existence signifie que le client doit examiner la tentative enregistrée avant d'envisager une nouvelle écriture. Un enregistrement illisible est un problème de reprise, pas une autorisation de créer une opération de remplacement.

Conserver les octets avant de les interpréter

Capturez une enveloppe de réponse bornée : statut, URL finale, indicateur de redirection, type de média, en-têtes pertinents, horodatage de la capture, octets reçus, condensat (digest) de ces octets et indicateur explicite de complétude. Enregistrez cette enveloppe avant d'en extraire des champs métier tels qu'un identifiant de page ou une clé d'API. Si la lecture s'arrête prématurément, conservez les octets reçus jusque-là avec l'indicateur de complétude à faux. Ne les complétez pas pour en faire un JSON d'apparence valide.

Un exemple concret d'implémentation est l'assistant de capture de réponses OpenAgentChat dans LinkFlow, épinglé sur une révision publique. Son assistant de mutation transmet une enveloppe bornée à un callback de persistance avant de la renvoyer, et il marque comme incomplet un corps partiel capturé. La frontière du callback mérite d'être examinée ; cette seule fonction n'établit ni la durabilité en base de données, ni le chiffrement, ni la reprise après plantage. Ces propriétés exigent du code de stockage distinct et des tests.

Une réponse peut contenir des identifiants d'accès à usage unique. Conservez l'enveloppe d'origine dans un stockage chiffré à accès contrôlé, avec une durée de rétention bornée adaptée à l'opération. Les diagnostics publics doivent contenir des noms d'étapes, des tailles et des codes d'erreur non secrets. Un condensat détecte une modification des octets ; il n'authentifie pas le serveur et ne rend pas la divulgation de données secrètes sans risque.

Promouvoir les conclusions séparément

Séparez l'interprétation du reçu de la vérification du résultat public. Un nouvel analyseur peut reconnaître une réponse complète jusque-là inconnue sans soumettre la requête une seconde fois. Cette promotion doit conserver l'enveloppe d'origine et consigner l'interprétation appliquée.

Un reçu peut identifier une ressource pour une consultation en lecture seule. Comparez l'identité propriétaire, l'identifiant de la ressource et le contenu attendu lorsque le service les expose. Si la page publique est une représentation distincte, vérifiez-la aussi. Un délai d'attente dépassé pendant cette vérification laisse une étape de vérification non résolue ; il n'annule pas l'écriture précédente.

Si aucun reçu exploitable ni aucune consultation faisant autorité n'existe, conservez explicitement un résultat inconnu. Toute action ultérieure suppose alors une décision de reprise fondée sur le contrat réel du service. Une clé de requête nouvellement générée ne prouve pas que l'opération précédente a échoué.

Cas de défaillance à tester

Testez une charge utile de succès inconnue, un corps tronqué, une réponse tardive après annulation, un échec de persistance et un redémarrage entre la capture et l'interprétation. Comptez les requêtes d'écriture physiques, pas seulement les appels de fonction. Vérifiez que la reprise préserve l'opération d'origine et qu'un échec de consultation publique ne peut pas déclencher une nouvelle requête de création.

Ce sont des vérifications proposées, non un benchmark publié ni une prétention à une exécution exactement une fois valable en toutes circonstances. L'assistant cité est un exemple d'implémentation lié au projet contributeur ; il ne constitue pas une recommandation quant à son adéquation à un autre système.