L'idempotence désigne la propriété d'une opération qui produit le même résultat quel que soit le nombre de fois où elle est exécutée. En HTTP, un PUT est idempotent (créer ou remplacer une ressource), un POST ne l'est pas (créer à chaque appel). C'est un concept fondamental dès qu'un traitement peut être rejoué : webhooks, imports, synchronisations, files de messages.
Pourquoi c'est critique
Les pannes réseau provoquent des retries automatiques, les webhooks peuvent être livrés plusieurs fois, les imports sont relancés après un incident. Sans idempotence, chaque rejeu risque de créer des doublons, un double débit ou un stock décrémenté deux fois.
Implémentation
Les techniques classiques : une clé d'idempotence envoyée par l'appelant, l'enregistrement des identifiants d'événements déjà traités, les opérations upsert fondées sur une clé métier unique, et des contraintes d'unicité en base comme dernier filet.
Le principe à retenir
Dans un système distribué, la livraison « exactement une fois » n'existe pas en pratique. Un message est livré au moins une fois, ou au plus une fois — et perdre des messages est rarement acceptable. On accepte donc qu'un même événement arrive plusieurs fois, et on rend son traitement idempotent. Ce n'est pas une optimisation : c'est la condition pour pouvoir rejouer un traitement en confiance après une panne.
Il ne faut pas confondre idempotence et dédoublonnement. L'idempotence est une garantie de correction : traiter deux fois le même message ne produit pas d'effet indésirable. Le dédoublonnement est une optimisation : on évite de traiter des messages devenus obsolètes. Les deux se combinent souvent.
Comment je l'applique
- Des upserts sur une clé métier. Pour les imports de stocks et de commandes, j'utilise un
INSERT … ON DUPLICATE KEY UPDATEsur une clé unique : si la ligne existe, elle est mise à jour, sinon elle est créée. Rejouer l'import ne crée aucun doublon. - Des exports en création-ou-remplacement. Vers une boutique, chaque produit est identifié par sa référence unique et envoyé par une opération qui crée ou remplace, plutôt que par une création seule.
- Des webhooks dédupliqués par identifiant d'événement. Le récepteur valide la signature, enregistre l'identifiant fourni par l'émetteur, répond immédiatement et traite en arrière-plan. Un événement déjà vu est ignoré.
- Des valeurs absolues plutôt que des deltas. « Le stock vaut 12 » est idempotent ; « retirer 1 au stock » ne l'est pas. Quand un flux le permet, je transmets l'état plutôt que la variation.
- Des empreintes pour éviter les réécritures inutiles. Comparer une empreinte normalisée des données avant d'écrire évite qu'un réimport identique soit traité comme une modification.
Des exemples concrets
Sur le hub de commandes d'une plateforme SaaS PIM/DAM, les commandes provenant des marketplaces sont importées de manière idempotente : si l'import est relancé après une panne réseau ou un timeout, les commandes déjà présentes sont mises à jour sans être dupliquées. Les stocks suivent le même principe, par lots, avec un historique de chaque mouvement pour tracer les écarts.
Sur un audit de charge pour Qezako, un réimport du même fichier CSV, sans aucune modification, purgeait le cache d'étiquettes de toutes les fiches : l'import recréait systématiquement les objets enfants, que l'ORM considérait comme modifiés. L'opération donnait le bon résultat, mais son effet de bord n'était pas idempotent. Une comparaison d'empreinte normalisée avant écriture a ramené un réimport identique à quelques secondes de lecture, sans écriture ni purge.
Les pièges à éviter
- Des traitements qui se chevauchent : un cron qui dépasse son intervalle relance le même travail en parallèle. Un verrou est alors nécessaire en plus de l'idempotence.
- Une clé d'idempotence mal choisie : un identifiant généré à chaque tentative ne protège de rien. Il doit être stable d'un rejeu à l'autre.
- Les effets externes : un e-mail envoyé ou un appel d'API payant ne s'annulent pas. Ils doivent être déclenchés une seule fois, après enregistrement de l'état.
- Oublier l'ordre : un message ancien qui arrive après un plus récent peut écraser une donnée fraîche. Un horodatage ou un numéro de version permet de l'ignorer.
L'idempotence, c'est ce qui sépare les intégrations fragiles des intégrations résilientes — la différence entre « ça marche » et « ça tient en production ».
L'idempotence est une exigence de base de toutes mes synchronisations entre ERP et e-commerce. Pour les webhooks, voir aussi Webhooks ou polling : quelle architecture pour le temps réel.