Idempotence

Vous envoyez une demande de création. La connexion se coupe avant la réponse. L’action a peut-être échoué, mais elle a peut-être réussi sans que vous le sachiez. Rejouer la demande sans protection peut alors créer un second paiement, un second contact ou un second message.

Une opération est idempotente lorsque plusieurs demandes identiques ont le même effet attendu qu’une seule. La norme HTTP considère notamment PUT, DELETE et les méthodes sûres comme idempotentes. Cette propriété concerne l’effet demandé par le client. Le serveur peut encore journaliser chaque requête séparément ou produire des réponses différentes. [S1]

L’idempotence ne signifie donc pas « exécuté une seule fois ». Elle signifie que répéter l’intention ne répète pas son effet métier attendu.

Trois contrats à ne pas confondre

Mécanisme	Ce qu’il protège	Exemple
Méthode HTTP idempotente	La répétition de la même intention sur une ressource	Remplacer une configuration avec PUT
Clé d’idempotence	Plusieurs tentatives d’une même commande non naturellement idempotente	Créer un paiement avec le même identifiant de tentative
Déduplication d’événements	Plusieurs livraisons du même événement	Ignorer un webhook dont l’identifiant a déjà été traité

Une méthode HTTP ne suffit pas à garantir le comportement métier. Un POST peut devenir rejouable si le serveur reconnaît la même opération grâce à une clé. À l’inverse, un point d’accès annoncé comme idempotent peut rester dangereux si son implémentation ajoute un nouvel effet à chaque appel.

Stripe enregistre le statut et le corps de la première demande associée à une clé d’idempotence, puis renvoie ce résultat lors des tentatives suivantes. Les paramètres doivent rester identiques. Une même clé réutilisée avec une autre commande est refusée. [S2]

Pour les webhooks, Stripe recommande de conserver les identifiants déjà traités et de ne pas répéter l’effet lorsqu’un même événement revient. [S3]

Concevoir une clé d’idempotence

Définissez cinq éléments avant l’implémentation.

1. La portée. Une clé est-elle unique pour tout le système, un compte, un point d’accès ou une opération précise ?
2. L’identité de la commande. Associez la clé à une empreinte des paramètres importants afin de refuser une réutilisation avec un autre contenu.
3. Le résultat conservé. Stockez l’état nécessaire pour renvoyer le même résultat ou signaler qu’une exécution est encore en cours.
4. La concurrence. Deux demandes portant la même clé peuvent arriver en même temps. Une écriture atomique doit désigner celle qui commence l’exécution.
5. La durée de conservation. Gardez la clé au moins pendant toute la période où une reprise ou une nouvelle livraison reste possible.

La clé doit être imprévisible ou suffisamment unique pour éviter les collisions. Elle ne doit pas contenir d’adresse email, de nom, de secret ou d’autre donnée sensible. Stripe recommande notamment un UUID version 4 ou une valeur aléatoire avec assez d’entropie. [S2]

Traiter une commande rejouable

Un flux simple suit cet ordre :

1. recevoir la commande, sa clé et ses paramètres ;
2. vérifier le format, l’autorisation et les règles métier ;
3. calculer l’identité stable de la commande ;
4. créer atomiquement un enregistrement en cours si la clé est nouvelle ;
5. renvoyer le résultat connu si la même clé et les mêmes paramètres existent déjà ;
6. refuser la clé si elle correspond à d’autres paramètres ;
7. exécuter l’effet externe une seule fois ;
8. enregistrer le résultat final avant de répondre ;
9. conserver la preuve pendant toute la fenêtre de reprise.

Si le processus s’arrête entre l’effet externe et l’enregistrement du résultat, la clé locale ne suffit pas. Utilisez aussi l’idempotence du système appelé, un identifiant métier unique ou une vérification de l’état externe avant de rejouer.

Choisir quoi rejouer

Un client peut répéter automatiquement une méthode idempotente lorsque la connexion échoue avant la lecture de la réponse. Il ne doit pas rejouer automatiquement une opération non idempotente sans preuve que sa sémantique est rejouable ou que la première demande n’a pas été appliquée. [S1]

Avant une reprise, demandez :

• l’erreur est-elle transitoire ?
• le résultat de la première tentative est-il inconnu ?
• l’opération est-elle naturellement idempotente ?
• une clé ou un identifiant stable protège-t-il l’effet ?
• le système distant conserve-t-il cette protection assez longtemps ?
• peut-on relire l’état réel avant de décider ?

Une clé d’idempotence ne transforme pas une erreur permanente en succès. Elle rend la répétition plus sûre. La politique de reprise décide encore si une nouvelle tentative est pertinente.

Tester la garantie

Vérifiez au minimum :

• deux demandes identiques envoyées successivement ;
• deux demandes identiques envoyées en parallèle ;
• une même clé avec des paramètres différents ;
• une coupure avant la réponse, puis une reprise ;
• un arrêt après l’effet externe mais avant l’enregistrement local ;
• une clé rejouée juste avant et juste après son expiration ;
• deux événements distincts qui décrivent le même objet ;
• un doublon reçu après une nouvelle livraison du fournisseur.

Le test réussi ne se limite pas au code HTTP. Il vérifie l’état final dans le système concerné : un seul paiement, un seul envoi, une seule création ou une seule transition métier.

Limites à garder visibles

• Une clé dupliquée par collision peut mélanger deux commandes légitimes.
• Une durée de conservation trop courte laisse passer un ancien rejeu comme une nouvelle opération.
• Une durée trop longue augmente le stockage et doit respecter la minimisation des données.
• L’idempotence d’un point d’accès ne protège pas un autre effet déclenché hors de son périmètre.
• Une réponse identique ne prouve pas que l’état externe est correct.
• La déduplication d’un événement ne remplace pas l’unicité métier lorsqu’un fournisseur crée deux événements distincts pour le même effet.

Rendez une opération rejouable avant d’ajouter des reprises. Définissez l’identité stable de la commande, protégez la concurrence, conservez le résultat assez longtemps et vérifiez l’effet final dans le système qui fait foi.