Idempotence : définition et usage en automatisation
L’idempotence signifie qu’une action répétée produit le même effet attendu qu’une seule exécution. RFC 9110 emploie ce terme pour les méthodes HTTP, et MDN explique qu’une méthode est idempotente si l’effet serveur d’une requête unique est le même que celui de plusieurs requêtes identiques.
Exemple simple
Mettre le statut d’une commande à paid est idempotent si répéter l’action laisse la commande à paid. Créer une nouvelle facture à chaque appel ne l’est pas.
Automatisation
Pour rendre un workflow idempotent, créez une clé unique métier : identifiant externe, type d’action, période. Avant de créer, essayez d’insérer cette clé dans une table avec contrainte unique. Si l’insertion échoue parce que la clé existe déjà, mettez à jour ou ignorez.
Piège concurrent
Un simple “je vérifie puis j’écris” ne suffit pas si deux exécutions tournent en même temps. Les deux peuvent vérifier avant qu’aucune n’écrive. Il faut une contrainte atomique côté base, une transaction ou un mécanisme équivalent.
Où l’utiliser
Webhooks, paiements, création de tickets, publication d’articles, envoi d’emails et reprises après erreur. Tout ce qui peut être relancé doit prévoir son garde-fou.
Idempotence côté API
Certaines APIs acceptent un header de type idempotency key pour les créations sensibles. Si le fournisseur le propose, utilisez une clé stable liée à l’action métier. Si le premier appel réussit mais que la réponse réseau est perdue, la relance avec la même clé doit permettre de retrouver le même résultat au lieu de créer un doublon.
Tracer la décision
Loguez la clé, l’action et le résultat : créé, déjà existant, mis à jour, ignoré. Cette trace aide à comprendre une reprise après incident. Sans elle, un opérateur peut relancer manuellement et produire précisément le doublon que l’idempotence devait éviter.
Exemple de clé
Pour un webhook de paiement : provider_payment_id + action. Pour une publication : source_article_id + site_id. Pour une relance email : lead_id + sequence_step. La clé doit représenter l’action unique, pas seulement l’utilisateur.
Limite
L’idempotence ne remplace pas la validation métier. Si la donnée source est fausse, répéter proprement l’action produira proprement un mauvais résultat. Elle protège surtout contre les doublons de transport, les retries et les reprises après panne.
Même effet ne signifie pas même réponse
Supprimer une ressource une première fois peut renvoyer un succès, puis un second appel peut signaler qu’elle n’existe plus. L’effet recherché reste le même : la ressource est absente. HTTP définit notamment PUT et DELETE comme idempotentes ; POST ne l’est pas par défaut, même si une API peut lui ajouter un mécanisme de clé d’idempotence.
La clé seule ne suffit pas
Enregistrer une clé avant l’appel d’un service externe crée un autre risque : si l’appel échoue, le prochain essai pourrait croire l’action terminée. Distinguez donc une demande réservée, en cours, réussie et à réconcilier. Une transaction locale ne rend pas atomique une action effectuée chez un autre prestataire.
Après un timeout, le résultat distant peut être inconnu plutôt qu’échoué. Recherchez l’opération avec son identifiant ou réutilisez la clé selon le contrat du fournisseur. Une clé créée à nouveau à chaque tentative supprime précisément la protection recherchée.