Idempotenza

Su HTTP la consegna è at-least-once: quando una richiesta non riceve risposta — per un timeout, una connessione caduta o un errore di rete — il client non può sapere se l'operazione è stata eseguita o se si è persa solo la risposta di ritorno. Ritentare rischia di duplicare l'operazione (una seconda anagrafica, una seconda fattura); non ritentare rischia di perderla.

L'Idempotency-Key risolve il dilemma: è una chiave che il client genera per una singola operazione logica e invia nell'header omonimo. Se una richiesta con la stessa chiave arriva una seconda volta, l'API non riesegue l'operazione e restituisce la risposta della prima. Ritentare diventa così sicuro.

Come si usa

Genera un valore univoco per operazione logica (ad esempio un UUID) e invialo nell'header su richieste POST e PUT:

POST /api/v3/1/Anagrafica
Idempotency-Key: 3f8c1e2a-9b47-4c65-8f2d-1a0e5b7c9d21
Content-Type: application/json

{ "nome": "ACME S.r.l.", ... }

• La prima richiesta viene eseguita normalmente e la sua risposta viene memorizzata.
• Un retry con la stessa chiave riottiene la stessa risposta (stesso status e stesso corpo), senza creare o modificare nulla. La risposta replicata riporta l'header Idempotent-Replayed: true.

L'header è opzionale: senza di esso il comportamento dell'API non cambia. È però fortemente consigliato ogni volta che una richiesta possa essere ritentata automaticamente.

Metodi supportati

L'idempotenza si applica a POST e PUT. Le richieste GET e DELETE sono già idempotenti per natura e non richiedono la chiave.

Riuso della chiave

La chiave è associata alla richiesta con cui è stata usata la prima volta:

• Se la stessa chiave viene inviata con una richiesta diversa (metodo, URL o corpo differenti), l'API risponde 422 Unprocessable Entity: è quasi sempre il segnale di una chiave riutilizzata per errore.
• Se un duplicato arriva mentre la prima richiesta è ancora in elaborazione, l'API risponde 409 Conflict: attendi e riprova.

Le chiavi vengono conservate per 24 ore; trascorso questo intervallo la stessa chiave viene trattata come nuova.

Idempotenza e concorrenza

L'idempotenza e il controllo della concorrenza risolvono problemi diversi e lavorano insieme:

• l'Idempotency-Key protegge dal ripetere lo stesso comando (il retry);
• il ConcurrencyToken protegge da modifiche concorrenti divergenti (due client che aggiornano la stessa entità).

Su una PUT, la chiave di idempotenza intercetta il retry e ne replica la risposta originale, evitando un 422 spurio da concurrency token; il controllo di concorrenza resta attivo come secondo livello di guardia per le modifiche realmente concorrenti.