Che cos’è l’idempotenza, e come le idempotency key rendono sicuri i retry?

Question

IT Interview Practice · Accepted Answer

L'**idempotenza** significa che eseguire un'operazione **più volte ha lo stesso effetto di eseguirla una sola volta**. Conta perché le reti sono inaffidabili: quando un client invia una richiesta e la risposta non arriva mai, non può sapere se il server l'ha elaborata. Se ritenta, un'operazione non idempotente potrebbe essere eseguita due volte.

## Il problema

```text
Client ──POST /payments {$100}──▶ Server   (charges $100 ✓)
Client ◀────────X (timeout)────── Server   (response lost)
Client ──POST /payments {$100}──▶ Server   (charges $100 AGAIN ✗ → $200!)
```

`GET`, `PUT` e `DELETE` sono naturalmente idempotenti, quindi ritentarli è sicuro. `POST` **non** lo è — è esattamente da qui che nascono addebiti duplicati e ordini duplicati.

## La soluzione: le idempotency key

Il client genera una **chiave unica** (di solito un UUID) per l'operazione logica e la invia in un header. Il server memorizza la chiave con il risultato; se la stessa chiave arriva di nuovo, restituisce il risultato **memorizzato** invece di rieseguire.

```http
POST /payments HTTP/1.1
Idempotency-Key: 5f2b8c1e-3a4d-4e6f-9c0b-1a2b3c4d5e6f
Content-Type: application/json

{ "amount": 100, "currency": "usd" }
```

```text
Server logic on receiving a request with an Idempotency-Key:
  1. Look up the key in a store (e.g. Redis/DB).
  2. If found → return the saved response (no re-charge).      ← the retry case
  3. If not  → process, save (key → response), then return.
  (Wrap 3 in a transaction / lock so concurrent retries don't double-execute.)
```

La **stessa chiave** al retry produce lo stesso `200` e lo stesso pagamento — il cliente viene addebitato una sola volta. È esattamente così che funziona l'API di Stripe.

## Perché è importante

Questa domanda separa gli ingegneri che progettano per l'happy path da quelli che progettano per il **fallimento**, che è ciò di cui si tratta l'affidabilità in produzione. I sistemi distribuiti garantiscono che timeout e fallimenti parziali *accadranno*, quindi qualsiasi endpoint con effetti collaterali — pagamenti, ordini, invio di denaro — ha bisogno di una strategia di retry, e "basta ritentare" è pericoloso per `POST`. L'intervistatore vuole sentire l'intuizione in due parti: primo, che l'idempotenza è una proprietà che puoi *progettare* (rendendo `PUT`/`DELETE` naturalmente sicuri, e dando a `POST` una **idempotency key** quando non può esserlo); e secondo, il dettaglio sottile di concorrenza — due retry che arrivano contemporaneamente non devono entrambi eseguire, quindi il controllo della chiave e la scrittura hanno bisogno di un lock o di un unique constraint. Farlo bene è la differenza tra addebitare un cliente una volta e addebitarlo due, ed è per questo che ogni API seria di pagamenti e commercio lo implementa.

Il problema

La soluzione: le idempotency key

Perché è importante

Domande correlate