Idempotence

Une opération est idempotente si la répéter a le même effet sur le serveur que de l’exécuter une seule fois. C’est important parce que les réseaux tombent en panne : un client qui reçoit un timeout ne sait pas si sa requête est arrivée, et réessayer n’est sûr que si la requête est idempotente. L’idempotence concerne l’état du serveur, pas le fait d’obtenir une réponse identique à chaque fois.

Quelles méthodes HTTP sont idempotentes

Méthode	Idempotente	Sûre (sans effet de bord)
GET, HEAD, OPTIONS	Oui	Oui
PUT	Oui	Non
DELETE	Oui	Non
POST	Non	Non
PATCH	Non garanti	Non

DELETE /orders/42 envoyé deux fois peut renvoyer 204 puis 404. Les réponses diffèrent, mais l’état est le même : la commande n’existe plus. C’est donc bien idempotent.

PUT ou PATCH

PUT remplace toute la ressource par le corps envoyé. Envoyer trois fois PUT /users/7 avec {"name": "Ada", "plan": "pro"} laisse à chaque fois le même utilisateur : c’est idempotent.

PATCH applique une modification, et son idempotence dépend de cette modification. {"plan": "pro"} fixe une valeur et est idempotent en pratique. Une opération comme « incrémenter loginCount de 1 », ou un add JSON Patch dans un tableau, donne un résultat différent à chaque fois : PATCH en tant que méthode n’est donc pas garanti idempotent.

Rendre un POST sûr à réessayer

Les API de paiement et de commande acceptent souvent une clé d’idempotence : le client génère une valeur unique et l’envoie dans un en-tête comme Idempotency-Key. Le serveur stocke le résultat de la première requête portant cette clé et renvoie le même résultat pour toute répétition, au lieu de créer une seconde commande.

POST /payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: 6f1c2a9e-3b7d-4f0a-9c2e-1d5b8a7e4f60

{"amount": 4999, "currency": "EUR"}

Comment la tester

• Envoyez deux fois le même PUT ou DELETE et vérifiez l’état de la ressource, pas seulement le code de statut.
• Envoyez deux fois le même POST avec la même clé d’idempotence. Attendez-vous à une seule ressource et au même corps de réponse.
• Réutilisez une clé avec un corps différent. Une API bien conçue le refuse au lieu de renvoyer silencieusement l’ancien résultat.
• Envoyez des requêtes en double de manière concurrente. C’est dans les situations de concurrence (race conditions) que la gestion de l’idempotence casse le plus souvent.