Pourquoi les endpoints GET qui modifient des données exigent-ils une approbation d’écriture ?

Un endpoint GET qui modifie l’état est une écriture déguisée. Le danger n’a rien de théorique. Les navigateurs, robots d’exploration, clients API, outils de supervision, services d’aperçu de liens, caches et agents effectuent tous des requêtes GET supplémentaires parce que le protocole leur indique que c’est sans danger. Si votre endpoint annule une tâche, renouvelle un jeton, envoie un message ou modifie un enregistrement, ces requêtes supplémentaires peuvent devenir des actions en production.

Les équipes découvrent souvent ces routes après un incident étrange, puis corrigent le seul endpoint qui a posé problème. C’est trop limité. Il faut trouver chaque appel qui ressemble à une lecture mais modifie quelque chose, classer son effet selon ses conséquences et le placer derrière la même frontière d’autorisation et d’audit qu’une écriture explicite. Changer le verbe compte, mais ce n’est qu’une partie de la correction.

Les méthodes HTTP sûres décrivent la sémantique demandée

Les endpoints GET qui modifient des données violent la promesse associée à cette méthode, même si leurs auteurs avaient une raison pratique de choisir GET. La RFC 9110 définit GET comme une méthode sûre et explique qu’une requête sûre ne demande pas au serveur de changer d’état. La RFC autorise des effets accessoires comme la journalisation et la comptabilité, car le client n’a pas demandé ces effets. Elle n’excuse pas une route dont le rôle prévu est d’apporter une modification.

Cette distinction déjoue une échappatoire fréquente : « Le serveur doit mettre à jour last_seen lorsqu’il lit l’élément. » Si le client a demandé à récupérer un élément et que le service met à jour un horodatage interne d’accès, cela peut être accessoire. Si le client a demandé à récupérer un élément et que le service marque une facture comme payée, crée une exportation, consomme un jeton ou fait avancer un workflow, la mutation est l’opération demandée. Appelez cela une écriture.

La RFC 9110 donne aussi la raison opérationnelle de s’en soucier. Les agents utilisateurs peuvent automatiser les méthodes sûres. Un navigateur peut récupérer une page pour créer un aperçu. Un robot peut suivre un lien. Une bibliothèque cliente peut réessayer après avoir perdu la réponse. La sémantique du protocole autorise ces acteurs à agir ainsi. Votre serveur ne peut pas compter sur le fait que chaque appelant a lu son exception non documentée.

Ne confondez pas « sûre » et « idempotente ». Une requête DELETE peut être idempotente parce que la répéter laisse la ressource supprimée, mais elle reste dangereuse parce que le premier appel change l’état. Une requête GET qui incrémente un compteur à chaque demande peut être idempotente seulement au sens étroit où elle s’arrête après un seuil, mais elle reste dangereuse car son but est de modifier l’état. Ces termes répondent à des questions différentes :

• Sûre demande si l’appelant a demandé un changement d’état.
• Idempotente demande si répéter la même requête produit le même effet attendu.
• Mettant en cache demande si un intermédiaire peut réutiliser une réponse.

Lorsqu’une équipe mélange ces termes, elle ajoute souvent une protection contre les nouvelles tentatives et décide que le problème est réglé. Éviter les doublons aide. Cela n’empêche pas un scanner de liens d’effectuer la première action destructrice.

Recherchez les conséquences, pas les noms de routes suspects

Vous trouvez les mutations cachées en suivant ce qu’une route provoque, pas en faisant confiance à son nom ou à son verbe. Des routes appelées getReport et view peuvent mettre du travail en file. Des routes appelées reset peuvent être parfaitement inoffensives si elles affichent un formulaire. Établissez votre inventaire à partir des données d’exécution et des chemins de code.

Commencez par chaque gestionnaire enregistré pour GET et HEAD. Pour chacun, suivez les écritures directes et les relais : transactions de base de données, publication dans une file, invalidation de cache ayant une portée métier, envoi d’e-mails ou de messages, paiements, changements d’identifiants, suppression de fichiers et appels sortants vers un autre service. Un gestionnaire GET qui appelle un service interne peut paraître propre dans son propre dépôt alors que cet appel interne effectue la mutation. Suivez-le jusqu’à pouvoir nommer l’effet final.

Cette recherche simple détecte beaucoup d’ancien code :

rg -n 'GET|\.get\(|router\.get\(|app\.get\(' src
rg -n 'INSERT|UPDATE|DELETE|enqueue|publish|sendMail|charge|revoke|rotate' src

La forme de la sortie est moins utile que le dossier de revue que vous créez à partir d’elle. Pour chaque constat, indiquez un endpoint, un déclencheur, l’effet final, le système concerné et la liste des appelants. N’écrivez pas « met à jour le statut » dans la colonne de l’effet. Écrivez « marque le déploiement d-481 comme annulé et envoie l’annulation à l’ordonnanceur ». Des entrées vagues permettent à un réviseur de laisser passer une action grave.

Les données d’exécution révèlent ce que la revue du code manque. Dans un environnement hors production, envoyez des requêtes représentatives avec un ID de corrélation. Interrogez ensuite les journaux applicatifs, les tables de tâches, les journaux d’appels sortants et les enregistrements d’audit pour cet ID. Si une requête GET mène à un message, une modification de ligne, un élément de file ou une requête externe, consignez toute la chaîne. Une route peut modifier l’état via un worker planifié quelques secondes plus tard, ce qui rend un simple journal de requêtes trompeur.

Surveillez les mutations que les développeurs écartent parce qu’elles ne sont pas des écritures dans une base relationnelle. Générer une URL de téléchargement à usage unique consomme une capacité. Lancer une exportation peut engendrer une facture élevée. Lire une route d’« acceptation d’invitation » peut ajouter un utilisateur à une organisation. Appeler un endpoint de rapport peut réveiller une tâche coûteuse d’entrepôt de données. La ressource renvoyée peut être en lecture seule alors que l’opération qui l’a produite ne l’est pas.

Les API existantes cachent des écritures à des endroits familiers

Les pires routes existantes ont généralement commencé comme des raccourcis pour une page destinée aux utilisateurs. Quelqu’un a rendu un lien d’administration facile à cliquer, puis un autre service a copié l’URL, puis un script en a dépendu, et le raccourci est devenu un contrat d’API.

Les liens de confirmation de réinitialisation de mot de passe sont un cas classique. Une route comme GET /reset/confirm?token=... paraît pratique car un navigateur peut l’ouvrir. Si l’ouverture de cette URL consomme le jeton et change le mot de passe, les scanners d’e-mails et les outils d’aperçu peuvent le consommer avant l’utilisateur. Une conception sûre utilise GET pour afficher un état de confirmation sans rien consommer, puis POST pour soumettre la confirmation. La page peut contenir une référence côté serveur de courte durée, mais l’écriture n’a lieu qu’après une action explicite.

Les liens de désabonnement demandent davantage de soin, pas moins. Les systèmes de messagerie et les lois sur la vie privée rendent le désabonnement en un clic attrayant, et certaines normes l’attendent. Si un scanner de sécurité de boîte aux lettres suit un tel lien, le destinataire peut perdre son abonnement sans toucher au message. Utilisez le mécanisme d’en-tête standard lorsqu’il s’applique, comprenez comment l’écosystème destinataire le traite et rendez le comportement de l’endpoint intentionnel. Ne copiez pas un modèle générique de « désabonnement GET » dans une API d’administration sans rapport et ne le présentez pas comme un précédent.

Parmi les autres cas fréquents :

• GET /jobs/123/retry, qui crée une nouvelle exécution à chaque actualisation d’un tableau de bord.
• GET /deployments/123/rollback, qu’une sonde de supervision peut appeler en testant les liens.
• GET /tokens/123/revoke, qui transforme une URL de support en capacité destructrice.
• GET /invoices/123/send, qui transforme un robot d’aperçu en expéditeur d’e-mails.
• GET /reports/monthly, qui lance silencieusement une exportation coûteuse au lieu d’en renvoyer une.

La recommandation répandue de « simplement exiger un paramètre secret dans la requête » est erronée. Les chaînes de requête se retrouvent dans l’historique du navigateur, les outils d’analyse, les journaux de serveurs, les en-têtes Referer dans certains flux, les captures d’écran et les messages copiés. Plus important encore, une URL secrète reste une URL GET. Toute personne ou tout système qui la reçoit peut déclencher l’action sans frontière d’approbation.

Les nouvelles tentatives et les aperçus amplifient le rayon d’impact

Un seul GET qui modifie l’état touche un public plus large que son auteur ne l’imagine, car les appelants automatisés le traitent comme répétable. Le premier symptôme paraît souvent aléatoire : une opération se produit deux fois, un compte change pendant la nuit ou un utilisateur voit une action qu’il n’a pas effectuée. Les journaux de requêtes affichent des identifiants légitimes, l’incident est donc qualifié d’erreur d’opérateur. Cette étiquette met souvent fin à l’enquête trop tôt.

Prenez un endpoint existant qui redémarre une compilation distante lorsqu’il reçoit GET /builds/77/retry. Un agent récupère l’URL sur un chemin réseau qui expire après que le serveur a accepté la requête. L’agent fait ce que font de nombreux clients HTTP et réessaie. La requête d’origine a déjà mis la compilation 311 en file, la seconde met la compilation 312 en file. Un tableau de bord charge ensuite un lien d’aperçu dans le flux d’activité et met la compilation 313 en file. Le gestionnaire peut renvoyer 200 OK à chaque fois, rien dans la réponse n’indique donc que l’opération a été dupliquée.

Une redirection peut réserver une autre surprise. Si une ancienne action GET redirige vers une nouvelle route et que la nouvelle route agit encore sur GET, la redirection préserve la sémantique dangereuse. Si la redirection modifie la méthode d’une manière que le client n’attend pas, les clients peuvent échouer de façon incohérente. Les redirections facilitent les migrations, elles ne doivent pas cacher une modification de la sémantique d’autorisation ou de méthode.

Les caches rendent l’échec plus étrange. Un cache partagé ne devrait pas stocker une réponse à un GET qui modifie l’état sans instructions explicites, mais les systèmes commettent des erreurs et les développeurs ajoutent mécaniquement des en-têtes de cache. Même sans mise en cache, un préchargeur peut émettre la requête avant que l’utilisateur décide d’agir. Ne bâtissez pas la sécurité sur l’espoir que chaque intermédiaire respecte votre intention privée.

La correction commence à la frontière. Une opération capable de modifier un système distant exige une demande d’action explicite avant que le client HTTP ne l’envoie. L’appelant doit voir un nom d’action, une cible et une conséquence distincts. Un délai d’attente après l’envoi devient alors une écriture incertaine, que l’appelant traite par une consultation d’état ou une clé d’idempotence plutôt que par une répétition aveugle.

Donnez aux actions un contrat qui ressemble à une écriture

Un endpoint corrigé doit exposer le changement dans son URI, sa méthode, son corps de requête, sa réponse et sa documentation. Vous n’avez pas besoin d’un débat REST centré sur les noms pour bien faire cela. Vous avez besoin d’un contrat qui empêche les appelants de prendre une action pour une récupération.

Pour l’exemple de compilation, utilisez un endpoint d’action POST et acceptez une clé d’idempotence. L’endpoint doit renvoyer une ressource qui identifie la nouvelle exécution, pas un message générique de réussite.

POST /v1/builds/77/retries HTTP/1.1
Idempotency-Key: 9ef8b462-97bf-4ca3-bb8b-4396a60ed9ae
Content-Type: application/json

{"reason":"retry after failed dependency download"}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /v1/builds/311

{"id":"311","source_build":"77","state":"queued"}

Stockez la clé d’idempotence avec le principal authentifié, le type d’action, la cible et l’empreinte de la requête. Si le même appelant renvoie la même clé et la même requête, renvoyez le résultat d’origine. S’il réutilise la clé avec un corps ou une cible différente, renvoyez un conflit. Un enregistrement de clé partagé globalement peut faire entrer en collision deux locataires, tandis qu’une clé qui ignore le corps de la requête peut transformer une erreur de copier-coller en mauvaise action.

Utilisez PUT ou PATCH lorsque la requête décrit l’état souhaité de la ressource. PATCH /v1/deployments/77 avec {"paused":true} peut convenir lorsque la ressource possède ce champ. POST /v1/deployments/77/rollback décrit mieux une commande qui crée une nouvelle exécution, une trace d’audit et éventuellement un résultat asynchrone. Ne forcez pas une commande dans PATCH uniquement pour satisfaire le guide de style de quelqu’un.

Renvoyez assez d’état pour qu’un appelant puisse se remettre d’une ambiguïté. Si une action s’exécute de façon asynchrone, renvoyez un ID d’opération et fournissez un endpoint GET qui ne lit que son avancement. Ce GET peut alors être réessayé, interrogé périodiquement, mis en cache selon ses en-têtes de réponse et ouvert dans un navigateur sans modifier le monde.

L’approbation doit précéder l’injection des identifiants

Une approbation après qu’une requête HTTP a quitté la machine n’est qu’une mise en scène. Un service distant peut agir avant que le client ne reçoive une réponse, et une réponse d’échec ne prouve pas qu’il n’a rien fait. Placez la décision là où la requête est construite, avant l’ajout des identifiants et avant que les octets quittent le processus.

Cela compte lorsqu’un agent de programmation IA appelle une API. L’agent peut déduire qu’une route est une lecture à partir de la description d’un outil, copier une ancienne URL depuis un dépôt ou suivre une suggestion dans un ticket. S’il dispose d’identifiants bruts, il peut effectuer l’appel avant qu’un humain ne voie l’endpoint. Un prompt qui demande au modèle d’être prudent n’est pas un contrôle d’autorisation.

Donnez à la couche d’approbation un modèle d’action normalisé. Il doit au moins contenir la méthode HTTP, l’hôte, le chemin, l’identifiant de cible lorsqu’il existe et une conséquence concise. La couche doit classer les actions à partir du contrat de service, pas seulement avec method === "GET". Une ancienne route GET qui appelle revokeToken doit suivre le même circuit d’approbation que POST /tokens/123/revoke jusqu’à sa suppression.

Une correspondance pratique peut ressembler à ceci :

{
  "method": "GET",
  "url": "https://api.example.test/v1/tokens/tk_42/revoke",
  "semantic_action": "revoke credential",
  "target": "tk_42",
  "approval": "required",
  "reason": "legacy GET endpoint changes remote credential state"
}

Ne présentez pas à la personne qui approuve un simple nom d’hôte et un bouton vert. L’invite doit lui indiquer que l’appel révoque un identifiant et nommer la cible qu’elle s’apprête à affecter. Si votre système ne peut pas déterminer l’action sémantique, traitez l’appel comme non classé et exigez une approbation. Autoriser tous les GET parce qu’ils sont des GET reproduit le défaut d’origine à un niveau plus profond.

L’autorisation par session et les contrôles d’identifiants par appel de Sallyport peuvent se placer à cette frontière pour les agents qui utilisent son canal HTTP. Le choix de conception important ne dépend pas de l’application : le détenteur du coffre exécute la requête, tandis que l’agent reçoit le résultat et non le secret.

Gardez les lectures utiles et les écritures difficiles à déclencher par accident

Le schéma de migration le plus net conserve un GET sûr pour la consultation et introduit un endpoint d’écriture distinct pour l’action elle-même. Vous pouvez garder une page conviviale, un endpoint d’état ou une réponse de simulation sans permettre à une récupération d’exécuter la commande.

Pour un générateur de rapports, GET /reports/monthly peut renvoyer le dernier rapport terminé et l’état actuel de génération. POST /reports/monthly/runs démarre une nouvelle génération. Pour une opération sur un identifiant, GET /tokens/tk_42 peut renvoyer des métadonnées, tandis que POST /tokens/tk_42/revocations crée un événement de révocation. Le segment de chemin supplémentaire est moins astucieux qu’un paramètre de requête d’action, mais il rend les journaux, les clients et les écrans de revue beaucoup plus clairs.

Une simulation mérite un contrat précis. POST /deployments/77/rollback?dry_run=true reste un POST parce que l’appelant a demandé l’évaluation d’une commande, même si elle ne valide rien. Renvoyez les cibles prévues, les préconditions attendues et les valeurs non résolues. Ne faites pas exécuter la planification de commande par GET /rollback?preview=true si cette planification acquiert elle-même des verrous, réserve de la capacité ou contacte un fournisseur avec un effet observable.

Certaines équipes tentent de préserver les anciennes intégrations en laissant l’ancien GET renvoyer une page HTML avec un formulaire qui soumet automatiquement un POST. Cela ne fait que déplacer le risque dans le navigateur. Utilisez une page qui exige une véritable interaction utilisateur et protégez le POST avec les défenses same-origin adaptées à l’application. Les clients API doivent recevoir une réponse de dépréciation claire et une date limite de migration, pas un document de navigateur qu’ils ne peuvent pas utiliser.

Testez les appelants qui ne demandent jamais la permission

Une route n’est pas corrigée tant que vous n’avez pas testé le comportement automatisé qui l’a rendue dangereuse. Les tests unitaires qui vérifient qu’un gestionnaire appelle une méthode de service ne suffisent pas. Testez la route comme la rencontreraient un navigateur, un client HTTP soumis à un délai d’attente, un robot d’exploration et un agent.

Pour chaque action migrée, effectuez ces vérifications dans un environnement isolé :

1. Envoyez deux fois l’ancien GET et confirmez qu’il ne peut pas créer deux actions. Pendant la transition, il doit échouer sans risque, afficher seulement un état de confirmation ou renvoyer une réponse de dépréciation.
2. Simulez un client qui perd la réponse après l’envoi, puis réessaie le POST avec la même clé d’idempotence. Confirmez que le service renvoie l’ID de l’action d’origine.
3. Récupérez plusieurs fois l’URL d’état sûre et confirmez qu’elle ne crée aucune tâche, aucun message, aucune écriture de grand livre ni aucun appel externe.
4. Tentez l’action avec une approbation expirée ou une session révoquée et confirmez que la requête n’atteint jamais le service distant.
5. Inspectez l’enregistrement d’audit et vérifiez qu’il identifie l’action normalisée, pas seulement la route de transport.

Utilisez l’injection de pannes au moment délicat : après que le serveur a validé l’action, mais avant d’envoyer une réponse. C’est là que les équipes découvrent si leur client réessaie aveuglément. Si la seule stratégie de reprise est « essayez encore », le contrat n’a pas donné assez d’informations à l’appelant.

Testez aussi les exemples de documentation. Une commande curl copiée dans un canal d’incident devient une interface opérationnelle. Si l’exemple utilise GET parce qu’il tient sur une ligne, quelqu’un l’automatisera. Rendez l’exemple de lecture sûre et l’exemple d’action explicite visiblement différents.

Auditez l’effet autant que la route

Une ligne d’audit qui indique GET /v1/builds/77/retry 200 est une mauvaise preuve. Elle consigne un fait de transport tout en cachant l’événement métier. Pendant un incident, l’enquêteur doit encore reconstituer si l’appel a lancé une compilation, relancé une précédente ou simplement renvoyé son état.

Consignez les deux niveaux. Conservez la méthode et la route reçues, car le comportement existant compte. À côté, consignez l’action sémantique, la cible, le processus ou le principal appelant, la décision d’approbation, l’identité de l’identifiant sans élément secret, l’ID de corrélation et la référence du résultat. Pour une commande asynchrone, journalisez l’ID de l’opération ou de la ressource créée afin que les événements ultérieurs soient reliés à la requête d’origine.

Un journal infalsifiable n’est utile que si vous pouvez le vérifier lorsque la confiance est devenue douteuse. Gardez le processus de vérification séparé du chemin de lecture normal de l’application. Sallyport projette ses journaux de session et d’appels depuis un journal d’audit chiffré, aveugle en écriture et chaîné par hachage, et sp audit verify vérifie cette chaîne hors ligne sur le texte chiffré. C’est le genre de propriété à exiger lorsqu’un agent avait l’autorité d’affecter un système externe.

Ne laissez pas la conservation des audits devenir un prétexte pour enregistrer des secrets. Les corps de requête contiennent souvent des identifiants, des jetons, des données personnelles ou des arguments de commande qui n’ont pas leur place dans un journal d’activité général. Journalisez une description normalisée et une empreinte là où vous avez besoin de preuves d’intégrité. Conservez les éléments sensibles uniquement là où les contrôles d’accès et les règles de conservation peuvent les prendre en charge.

Supprimez l’exception au lieu de la documenter indéfiniment

L’état final ne comporte aucune route GET qui modifie l’état, même si une passerelle d’approbation les intercepte actuellement. Maintenir l’exception invite un nouveau client, une URL copiée ou une future refactorisation à contourner la table de classification. La couche de compatibilité doit avoir un responsable, un inventaire des appelants et une date à laquelle elle cesse d’accepter l’ancien format.

Commencez par l’endpoint susceptible de provoquer le résultat le plus irréversible. Ajoutez un contrat POST explicite, un comportement d’idempotence, une classification d’approbation et un enregistrement d’audit au niveau de l’effet. Rendez ensuite observable chaque ancien appel GET. Lorsque vous pouvez nommer les appelants restants, faites-les migrer délibérément au lieu de rompre par surprise une intégration cachée.

N’acceptez pas « notre client sait mieux » comme propriété de sécurité. Une requête GET traverse des systèmes conçus pour la répéter et l’inspecter. Faites ressembler votre écriture à une écriture avant que l’un de ces systèmes décide de vous aider.