Idempotenz

Wozu#

Bekommt deine App auf ein POST keine Antwort, weiß sie nicht, ob es angekommen ist: wurde die Bestellung angenommen, die Reservierung angelegt? Ohne Schutz legt eine Wiederholung eine zweite Reservierung an. Mit Idempotency-Key antwortet Flavoso auf die Wiederholung mit dem Ergebnis des ersten Versuchs.

So geht es#

• Schick bei POST den Kopf Idempotency-Key mit einer eindeutigen Zeichenkette: 1 bis 255 druckbare ASCII-Zeichen. Bei PUT, PATCH und DELETE beachtet Flavoso den Kopf nicht.
• Der Schlüssel gilt je Verbindung. Flavoso hält die erste Antwort (Status und Rumpf) 24 Stunden.
• Kommt dieselbe Anfrage mit demselben Schlüssel noch einmal, kommt die erste Antwort zurück, mit Idempotent-Replayed: true, und nichts passiert ein zweites Mal.
• Verglichen werden Methode, Pfad und die rohen Bytes des Rumpfs. Eine Wiederholung schickt also genau denselben Rumpf: schon andere Leerzeichen oder eine andere Reihenfolge der Felder machen daraus eine andere Anfrage, und derselbe Schlüssel mit einer anderen Anfrage ergibt 422 idempotency_key_reused.
• Läuft die erste Anfrage noch, ergibt die zweite 409 idempotency_in_progress. Kurz warten, dann wiederholen. Ist die erste nie fertig geworden (bei uns abgebrochen), ist der Schlüssel nach 2 Minuten wieder frei.
• Eine Antwort mit 5xx oder 409 conflict wird nicht gehalten: die Wiederholung wird ausgeführt.

# 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", ... }

Gute Schlüssel#

Der Schlüssel gehört zur Operation, nicht zum Versuch. Erzeuge ihn einmal, wenn dein Programm beschließt, etwas zu tun, und benutze ihn für jede Wiederholung genau dieser Operation.

• Aus deinen eigenen Daten abgeleitet: accept-<Bestellkennung>, ack-<Bestellkennung>, booking-<deine Buchungsnummer>.
• Oder eine UUID, gespeichert zusammen mit dem Auftrag in deiner Warteschlange.
• Nie ein neuer Schlüssel je Versuch: dann schützt er vor nichts.

Was ohnehin wiederholbar ist#

• Statuswechsel: eine Bestellung, die schon auf dem Zielstand steht, kommt unverändert mit 200 zurück, und accept gibt eine Bestellung, die schon hinter pending steht, unverändert zurück.
• POST /orders/{id}/acknowledge: einmal übernommen bleibt übernommen; dieselbe external_id noch einmal ändert nichts.
• PUT /menu, PUT /store/hours, POST /menu/availability und jedes PATCH: sie setzen einen Zielzustand und schalten nicht um. Zweimal ergibt dasselbe wie einmal.

Bei POST schadet ein Idempotency-Key trotzdem nie und macht auch die Antwort gleich; bei PUT und PATCH beachtet Flavoso ihn nicht.