Concevoir des opérations idempotentes et des nouvelles tentatives sûres

Objectif

Un client dont la requête se termine en délai d'expiration doit pouvoir la relancer sans risque : pas de commande dupliquée, pas de paiement dupliqué, pas d'article dupliqué.

Prérequis

La RFC 9110 qualifie une méthode d'idempotente lorsque l'effet voulu de plusieurs requêtes identiques sur le serveur est le même que celui d'une seule ; PUT, DELETE et les méthodes sûres (GET, HEAD, OPTIONS, TRACE) le sont, POST ne l'est pas. La même RFC précise qu'un client ne devrait pas relancer automatiquement une requête utilisant une méthode non idempotente, sauf s'il sait que la sémantique est réellement idempotente. Pour POST, le brouillon IETF « The Idempotency-Key HTTP Header Field » (groupe de travail HTTPAPI ; version 07 d'octobre 2025, expiré au moment de la rédaction en septembre 2026 et non publié comme RFC) décrit l'en-tête qu'utilisent Stripe et d'autres fournisseurs. Sont nécessaires un stockage pour un petit enregistrement par clé, ainsi que des clients qui génèrent une clé unique par opération logique.

Étapes

1. Choisir les méthodes selon la RFC 9110 : modifier via PUT sur une adresse connue, supprimer via DELETE ; toutes deux peuvent être relancées sans mécanisme supplémentaire.
2. Pour les requêtes POST créatrices, accepter un en-tête Idempotency-Key. Le brouillon recommande un UUID ou un identifiant comparablement aléatoire ; Stripe suggère des UUID v4, autorise jusqu'à 255 caractères, et déconseille d'utiliser des données sensibles comme clé.
3. À la première arrivée, stocker la clé avec une empreinte de la requête (hash sur le chemin et le corps), le compte et le résultat (statut, corps de réponse) — dans la même transaction que l'opération elle-même, ou sous un verrou sur la clé, afin que deux nouvelles tentatives simultanées ne passent pas toutes les deux.
4. En cas de réutilisation de la clé avec la même empreinte, renvoyer la réponse stockée inchangée. En cas de même clé avec un corps différent, répondre 422, comme le prévoit le brouillon ; si la requête originale est encore en cours, répondre 409.
5. Supprimer les clés après un délai documenté ; Stripe décrit une suppression au plus tôt après 24 heures, et traite une clé réutilisée après ce délai comme une nouvelle requête.
6. Consigner le format de clé, le délai et le comportement en cas de conflit dans la documentation de l'API, afin que clients et agents puissent s'y fier au lieu de deviner.

Résultat attendu

Un client qui relance avec la même clé après un délai d'expiration obtient exactement une ressource créée, et deux fois la même réponse.

Limites et base de vérification

L'idempotence couvre l'état du propre serveur, pas les effets de bord dans des systèmes tiers (un e-mail envoyé deux fois par un service en aval). Les clés doivent être séparées par compte, sinon les clients entrent en collision. Le brouillon n'est pas une RFC et a actuellement expiré ; les affirmations sur l'en-tête et les codes de statut suivent le brouillon et la documentation Stripe citée, aucune mesure n'est revendiquée.