Idempotenza

Un’operazione è idempotente se ripeterla ha sul server lo stesso effetto che eseguirla una volta sola. Conta perché le reti falliscono: un client che va in timeout non sa se la sua richiesta è arrivata, e ritentare è sicuro solo quando la richiesta è idempotente. L’idempotenza riguarda lo stato del server, non il fatto di ricevere ogni volta una risposta identica.

Quali metodi HTTP sono idempotenti

Metodo	Idempotente	Sicuro (nessun effetto collaterale)
GET, HEAD, OPTIONS	Sì	Sì
PUT	Sì	No
DELETE	Sì	No
POST	No	No
PATCH	Non garantito	No

DELETE /orders/42 inviato due volte potrebbe restituire 204 e poi 404. Le risposte sono diverse, ma lo stato è lo stesso: l’ordine non c’è più. È comunque idempotente.

PUT e PATCH a confronto

PUT sostituisce l’intera risorsa con il body che invii. Inviare tre volte PUT /users/7 con {"name": "Ada", "plan": "pro"} lascia ogni volta lo stesso utente, quindi è idempotente.

PATCH applica una modifica, e se sia idempotente dipende dalla modifica. {"plan": "pro"} imposta un valore ed è idempotente nella pratica. Un’operazione come “incrementa loginCount di 1”, o un add JSON Patch su un array, dà ogni volta un risultato diverso, quindi PATCH come metodo non è garantito idempotente.

Rendere una POST sicura da ritentare

Le API di pagamento e di ordini accettano spesso una chiave di idempotenza: il client genera un valore univoco e lo invia in un header come Idempotency-Key. Il server memorizza il risultato della prima richiesta con quella chiave e restituisce lo stesso risultato per ogni ripetizione, invece di creare un secondo ordine.

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

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

Come testarla

• Invia due volte la stessa PUT o DELETE e verifica lo stato della risorsa, non solo lo status code.
• Invia due volte la stessa POST con la stessa chiave di idempotenza. Aspettati una sola risorsa e lo stesso body di risposta.
• Riusa una chiave con un body diverso. Un’API ben progettata lo rifiuta invece di restituire in silenzio il vecchio risultato.
• Invia richieste duplicate in concorrenza. Le race condition sono il punto in cui la gestione dell’idempotenza di solito si rompe.