La finance est l'un des domaines les plus clairs où la conception d'API doit supposer que le réseau est peu fiable. Les utilisateurs réessaient. Les clients mobiles se reconnectent. Les passerelles expirent. Les travailleurs en arrière-plan rejouent des messages.
Si le serveur ne peut pas reconnaître une demande logiquement identique et restituer le même résultat en toute sécurité, le système n'est pas suffisamment défensif pour le mouvement d'argent.
À quoi ressemble un contrat idempotent
Une requête API typique inclut une clé d'idempotence :
POST /payments
Idempotency-Key: 8b7b1b1c-8c3d-4ff0-a87a-5a148f7d4d4e
Le serveur stocke la clé avec le résultat de la première tentative de traitement réussie. Si la même demande arrive à nouveau, elle retourne le résultat original au lieu de créer un second paiement.
C'est le point architectural important : l'idempotence n'est pas un simple truc de reprise. C'est un contrat côté serveur.
En pratique, cela signifie généralement que la clé est persistée avec une garantie d'unicité et associée à la forme normalisée de la demande ainsi qu'à la charge utile ou au dossier de résultat précédent.
Pourquoi cela est plus important que la logique de reprise
Les tentatives sont normales dans les systèmes distribués. Le mouvement d'argent en double ne l'est pas.
Sans idempotence, les tentatives peuvent créer :
- des frais en double
- des entrées de registre en double
- une réconciliation en aval incohérente
C'est pourquoi l'idempotence doit faire partie du chemin d'écriture avant que quiconque ne commence à célébrer un middleware de reprise astucieux.
Règle Améliorée
Si l'opération peut déplacer de l'argent ou créer un effet secondaire durable, concevez l'endpoint pour reconnaître une intention de double. En finance, l'idempotence fait partie de la correction, pas seulement de la résilience.
Lectures Complémentaires