Idempotence d’une API de signature : éviter les doubles procédures
Un timeout ne doit jamais créer deux demandes ni envoyer deux invitations. Concevez clés, empreintes, verrous et réponses rejouables.
Le client envoie une création, attend dix secondes et reçoit un timeout. Il ne sait pas si le serveur a échoué avant ou après la création. Un retry naïf peut produire deux procédures, deux invitations et deux consommations de quota.
L’idempotence transforme cette ambiguïté en contrat. La plateforme associe une clé stable à l’intention et retourne le même résultat pour les répétitions compatibles.
Définir la portée de la clé
La clé doit être unique dans un périmètre documenté, généralement une organisation et une opération. Le client la génère à partir d’une référence stable ou d’un UUID conservé avant l’appel. Une nouvelle tentative métier volontaire utilise une nouvelle clé.
Calculez une empreinte canonique des paramètres pertinents. Si la clé existe avec une empreinte différente, répondez par un conflit. Accepter silencieusement le nouveau payload masquerait une erreur et pourrait rattacher le mauvais document.
Gérer concurrence et états intermédiaires
Insérez la réservation d’idempotence avec une contrainte unique avant l’effet. Les requêtes concurrentes doivent observer un état en cours, terminé ou échoué de manière récupérable. Évitez le verrou mémoire, inefficace entre plusieurs instances.
Stockez code HTTP, réponse utile, ressource créée et empreinte. Définissez ce qui se passe si le processus tombe après création mais avant enregistrement de la réponse : la transaction ou une reprise doit pouvoir reconstruire le résultat.
Étendre le principe aux effets externes
Une procédure unique ne suffit pas si l’e-mail est envoyé deux fois ou le quota débité deux fois. Utilisez un outbox transactionnel ou des commandes aval elles-mêmes idempotentes. Chaque effet possède une clé dérivée stable.
Exposez aux opérateurs la relation entre clé, ressource et effets. Une correction manuelle ne doit pas supprimer la preuve d’un doublon ; elle doit créer un ajustement audité.
Grille de décision
| Étape | Clé stable | Réponse à un retry |
|---|---|---|
| Création | Organisation + référence | Même procédure |
| Activation | Procédure + version | Même état d’activation |
| Invitation | Procédure + signataire | Pas de second envoi non voulu |
| Quota | Transaction d’activation | Même écriture ledger |
| Webhook | Identifiant d’événement | Même effet métier |
Plan d’action
- Documenter le périmètre de clé
- Comparer l’empreinte du payload
- Utiliser une contrainte en base
- Conserver la réponse rejouable
- Rendre les effets aval idempotents
- Tester concurrence et crash aux frontières
Questions fréquentes
Combien de temps conserver une clé ?
Au moins pendant la fenêtre réaliste de retry et selon l’importance de l’opération. La durée doit être documentée.
Peut-on utiliser l’identifiant du document ?
Seulement s’il représente réellement une intention unique et reste stable. Un UUID dédié est souvent plus clair.
Un POST peut-il être idempotent ?
Oui au niveau applicatif lorsque l’API définit une clé et un comportement de répétition explicites.
Sources officielles et techniques
Important
Ce contenu fournit une information générale et ne remplace pas un avis juridique ou un audit de conformité. Le niveau de signature adapté dépend du contexte, de l’identification, de l’authentification et des preuves effectivement produites.