Idempotenza

A cosa serve#

Se la tua app non riceve risposta a un POST, non sa se è arrivato: l'ordine è stato accettato, la prenotazione creata? Senza protezione, una ripetizione crea una seconda prenotazione. Con Idempotency-Key Flavoso risponde alla ripetizione con il risultato del primo tentativo.

Come funziona#

• Con POST invia l'intestazione Idempotency-Key con una stringa univoca: da 1 a 255 caratteri ASCII stampabili. Con PUT, PATCH e DELETE Flavoso ignora l'intestazione.
• La chiave vale per collegamento. Flavoso conserva la prima risposta (stato e corpo) per 24 ore.
• Se la stessa richiesta arriva di nuovo con la stessa chiave, torna la prima risposta, con Idempotent-Replayed: true, e nulla accade una seconda volta.
• Si confrontano metodo, percorso e byte grezzi del corpo. Una ripetizione deve quindi inviare esattamente lo stesso corpo: basta una spaziatura diversa o un altro ordine dei campi per renderla una richiesta diversa, e la stessa chiave con una richiesta diversa dà 422 idempotency_key_reused.
• Se la prima richiesta è ancora in corso, la seconda dà 409 idempotency_in_progress. Aspetta un momento, poi riprova. Se la prima non è mai terminata (interrotta da parte nostra), la chiave torna libera dopo 2 minuti.
• Una risposta 5xx o 409 conflict non viene conservata: la ripetizione viene eseguita.

# Create the key ONCE per operation and keep it for every retry of that operation
KEY=$(uuidgen)
curl -X POST https://api.flavoso.com/v1/orders/ORDER_ID/accept \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $KEY"
# No answer? Send exactly the same command again, with the same $KEY.

HTTP/1.1 200 OK
Idempotent-Replayed: true
X-Request-Id: req_9a1b2c3d4e5f60718293a4b5
Content-Type: application/json

{ "object": "order", "id": "cce01f52-5188-410f-9659-6ce26ba9b784", "status": "confirmed", ... }

Chiavi ben scelte#

La chiave appartiene all'operazione, non al tentativo. Generala una volta, quando il tuo programma decide di fare qualcosa, e usala per ogni ripetizione proprio di quell'operazione.

• Derivata dai tuoi dati: accept-<id ordine>, ack-<id ordine>, booking-<tuo numero di prenotazione>.
• Oppure un UUID, salvato insieme al job nella tua coda.
• Mai una nuova chiave per ogni tentativo: così non protegge da nulla.

Cosa è ripetibile comunque#

• Cambi di stato: un ordine che è già nello stato di destinazione torna invariato con 200, e accept restituisce invariato un ordine che ha già superato pending.
• POST /orders/{id}/acknowledge: preso in carico resta preso in carico; lo stesso external_id una seconda volta non cambia nulla.
• PUT /menu, PUT /store/hours, POST /menu/availability e ogni PATCH: impostano uno stato di destinazione e non fanno da interruttore. Inviarli due volte ha lo stesso effetto che inviarli una volta.

Con POST un Idempotency-Key comunque non guasta mai e rende identica anche la risposta; con PUT e PATCH Flavoso lo ignora.