Prenons un scénario fictif : un portail demande la création d’une commande, mais la réponse n’arrive jamais. L’opération a-t-elle échoué, ou seule la réponse a-t-elle été perdue ? L’idempotence des API aide à traiter cette incertitude, à condition d’en définir clairement les garanties.
Un délai d’attente dépassé ne signifie pas un échec
Pour l’appelant, l’absence de réponse laisse le résultat incertain. Renvoyer une demande de création sans contrat adapté peut créer une deuxième commande. La distinction essentielle se situe entre la reprise d’une même intention métier et l’expression d’une nouvelle intention.
La RFC 9110 définit l’idempotence par l’effet intentionnel sur le serveur, pas nécessairement par une réponse identique. PUT, DELETE et les méthodes HTTP sûres sont idempotentes selon cette définition. Un client ne devrait pas réessayer automatiquement une méthode non idempotente, sauf s’il sait que l’opération est effectivement idempotente ou peut établir que la requête initiale n’a pas été appliquée.
Définir un contrat d’idempotence explicite
Un identifiant fourni par l’appelant permet de distinguer les tentatives répétées des intentions distinctes. Comme l’explique l’Amazon Builders’ Library, comparer les paramètres ne suffit pas : deux commandes identiques peuvent être intentionnelles. Dans le contrat proposé, l’appelant génère une clé pour une intention métier et la conserve lors des reprises, plutôt que d’en créer une après chaque délai dépassé.
Documentez la portée de cette clé : à quel appelant et à quelle opération elle se rattache, comment traiter des paramètres modifiés et quelle réponse fournir pendant ou après le traitement. Précisez la durée de conservation du registre et le comportement après expiration. Restituer une réponse enregistrée constitue une garantie contractuelle supplémentaire, pas la définition de l’idempotence HTTP.
Traiter les doublons, y compris simultanés
Une clé ne suffit pas si deux requêtes peuvent toutes deux franchir le contrôle des doublons. Pour notre commande fictive, limitons le périmètre à une écriture métier et à son registre d’idempotence dans une même frontière transactionnelle. Le mécanisme décrit par AWS exige des propriétés ACID pour l’enregistrement du jeton et les modifications associées. La conception doit coordonner les tentatives concurrentes afin qu’elles ne créent pas indépendamment la même commande attendue.
La séquence illustrative est simple : recevoir la clé, coordonner l’accès à son registre, créer la commande et enregistrer son résultat de manière atomique, puis répondre. Si la réponse se perd, la reprise s’appuie sur le registre existant selon le contrat convenu. Ce raisonnement couvre la transaction locale, pas une chaîne de services externes.
Stripe API v1 fournit un exemple précis : dès que l’exécution du point d’accès commence, le code et le corps de la première réponse sont conservés, y compris une erreur 500, pour les reprises avec la même clé. Des paramètres différents provoquent une erreur tant que la clé reste connue. Les clés peuvent être supprimées lorsqu’elles ont au moins 24 heures ; leur réutilisation après suppression déclenche une nouvelle requête. Ces règles propres au fournisseur ne sont pas des valeurs universelles.
Valider les garanties avant la mise en production
Traduisez le contrat en scénarios de test, en précisant pour chacun le résultat métier et la réponse API attendus :
- Perdre la réponse après une écriture réussie, puis réessayer avec la même clé.
- Envoyer des requêtes simultanées avec la même clé.
- Réutiliser une clé connue avec des paramètres différents.
- Réessayer après expiration de la durée de conservation de la clé.
- Interrompre le traitement entre les étapes et vérifier la cohérence entre l’écriture métier et le registre d’idempotence.
Avant d’automatiser les reprises, passez en revue les opérations sensibles et formalisez leurs garanties, leur périmètre et leurs limites. Cette grille peut structurer une revue de conception avec Halsson, sans confondre un contrat d’idempotence délimité avec une promesse d’exécution exactement une fois de bout en bout.