Outils de développement · Générateur UUID
Clés d'idempotence : utilisation d'un UUID généré par le client pour sécuriser les tentatives
· Pourquoi c'est important
uuid cryptographie API du navigateur
Un délai d'attente sur une demande de paiement vous laisse incertain si elle a été exécutée. Les clés d'idempotence vous permettent de réessayer en toute sécurité, et un UUID généré par CSPRNG est la clé naturelle. Cet article explique le modèle de bout en bout.
Le délai d'attente qui aurait pu facturer le client deux fois — les clés d'idempotence du mode de défaillance existent pour y remédier
Un timeout lors d'une demande de paiement crée une véritable incertitude pour le client et le système. Votre client HTTP a abandonné l'attente d'une réponse, mais le serveur de paiement a peut-être traité la transaction avant la fermeture ou l'expiration du délai de connexion. Si vous réessayez la même demande, vous risquez de facturer le client deux fois. Si vous ne réessayez pas, le paiement ne sera jamais effectué. Le système de paiement échoue dans un compromis malheureux : l'argent du client peut avoir disparu, peut arriver demain, peut être bloqué dans une file d'attente de traitement ou peut ne pas avoir quitté le compte du tout. Cette ambiguïté est inacceptable pour les systèmes financiers.
Comment fonctionnent les clés d'idempotence : le serveur stocke la première réponse sous la clé et la rejoue pour les répétitions
Les clés d'idempotence résolvent ce problème avec élégance en rendant les tentatives sûres et déterministes. Le client génère une clé unique pour chaque intention (un paiement, un transfert, une charge) et l'inclut dans chaque demande. Le serveur traite le paiement, met en cache la réponse sous cette clé et stocke à la fois la clé et le résultat. Si la même clé arrive à nouveau dans une fenêtre de conservation, le serveur relit la réponse mise en cache sans traiter à nouveau le paiement. Le client peut réessayer en toute confiance, sachant que la même clé donnera toujours le même résultat, quel que soit le nombre d'envois. Ce modèle élimine toute ambiguïté et sécurise la logique de nouvelle tentative.
Générer avant la première tentative : pourquoi la clé doit exister avant le départ de la requête et être réutilisée textuellement lors d'une nouvelle tentative
Le modèle est plus ancien que les spécifications HTTP modernes, mais il a pris de l'importance dans les paiements après des pertes financières généralisées et des plaintes de clients concernant des frais en double. Chaque API de paiement et de nombreuses API de services Web prennent désormais en charge les clés d'idempotence. Un UUID généré par CSPRNG est le choix naturel pour la clé car il est indevinable, unique sans aucune coordination entre les clients et ne nécessite aucune allocation côté serveur ni autorité centrale. Le client le génère avant la première tentative, le réutilise textuellement à chaque nouvelle tentative et reçoit la même réponse à chaque fois. Aucun état côté serveur n’est nécessaire pour coordonner la génération de clés.
Pourquoi un UUID aléatoire et non un hachage de compteur ou de charge utile - unicité sans coordination et pas de réutilisation accidentelle entre les intentions
La clé doit exister avant que la requête ne quitte le client car sa génération lors d'une nouvelle tentative est trop tardive pour garantir l'idempotence. Si la première demande aboutissait et facturait le client, la génération d'une nouvelle clé lors de la nouvelle tentative masquerait le problème et facturerait à nouveau. Le client doit s'engager sur une clé avant la première tentative, la stocker en mémoire ou dans un stockage persistant, et réutiliser cette même clé si un délai d'attente ou une nouvelle tentative devient nécessaire. Pour les tests manuels de l'API, le générateur ToolAcre produit des clés que vous pouvez coller dans curl ou un client REST, copier et réutiliser sur plusieurs requêtes pour tester le comportement d'idempotence.
Portée et durée de vie : clés par opération, par compte et durée pendant laquelle le serveur doit les mémoriser
Pourquoi un UUID plutôt qu'un hachage ou un compteur séquentiel pour les clés d'idempotence ? Un hachage de la charge utile de la requête semble intuitif : des charges utiles identiques obtiennent des hachages identiques et donc des clés identiques. Mais les hachages sont faibles pour ce cas d'utilisation car deux requêtes presque identiques avec des montants différents, des destinataires différents ou des paramètres différents produisent des hachages complètement différents et génèrent ainsi des frais distincts, ce qui est correct mais n'offre pas toute la protection nécessaire. Un compteur séquentiel nécessite une coordination et un état distribué : si deux clients génèrent tous deux des clés basées sur des compteurs sur votre infrastructure, leurs compteurs peuvent entrer en collision. Un UUID ne nécessite aucune autorité centrale, est indevinable et il est extrêmement peu probable qu'il entre en collision par hasard sur l'ensemble d'Internet à tout moment.
Exemple concret : une séquence de nouvelle tentative avec la même clé, montrant ce que le client envoie et ce que le serveur renvoie à chaque fois
L'implémentation côté serveur stocke les réponses sous des clés et renvoie les réponses mises en cache lors des répétitions. La complexité réside dans la résolution de questions opérationnelles pratiques : la période de conservation, la durée de mémorisation d'une clé, la taille du cache, le nombre de clés à mémoriser, le verrouillage, comment empêcher deux demandes simultanées avec la même clé de traiter le paiement deux fois et le nettoyage du moment où il faut oublier une clé. Il s'agit de questions de stockage et de fiabilité qui ne relèvent pas du champ d'application du générateur UUID. Le travail du client consiste à générer une bonne clé et à la réutiliser lors des tentatives ; le travail du serveur est d'implémenter le cache correctement et durablement.
Ce que cela ne couvre pas : le stockage et le verrouillage côté serveur nécessaires à la mise en œuvre du modèle, qui est une conception distincte
Un exemple concret montre une séquence typique dans la pratique. Une application mobile doit transférer de l'argent à un ami à l'aide d'une API prenant en charge l'idempotence. Avant d'envoyer la demande, l'application génère un UUID à l'aide de sa bibliothèque de chiffrement locale ou en récupère un à partir du générateur ToolAcre à des fins de test : 3fa85f64-5717-4562-b3fc-2c963f66afa6. L'application envoie une requête POST à /transfers avec un corps JSON et un en-tête HTTP Idempotency-Key : 3fa85f64-5717-4562-b3fc-2c963f66afa6. Le serveur traite le transfert, stocke 3fa85f64-5717-4562-b3fc-2c963f66afa6 → {status : "success", transferId : "xfer-12345"} dans son cache et renvoie une réponse 200 avec le résultat.
À retenir : une intention, une clé – le générateur ToolAcre vous donne un UUID soutenu par CSPRNG à utiliser comme clé lors du test manuel d'une intégration.
Le délai réseau expire et le client ne voit pas la réponse dès la première tentative. L'application réessaye la même demande avec la même clé d'idempotence sans générer de nouveau UUID. Le serveur reconnaît la clé dans son cache, trouve la réponse mise en cache et renvoie immédiatement {status : "success", transferId : "xfer-12345"} sans traiter un nouveau transfert et sans facturer à nouveau le client. L’opération est idempotente : réessayer produit à chaque fois le même résultat observable. Pour un test fonctionnel, le générateur ToolAcre peut fournir la clé ; générez un UUID, incluez-le dans l'en-tête, observez la réponse et renvoyez-le avec la même clé pour vérifier que le serveur implémente correctement la mise en cache.