Idempotenz & Revision

Warum ein Wiederholen nach einem Netzfehler sicher ist und wie gleichzeitige Änderungen sich nicht gegenseitig überschreiben.

Ein Key, vier Ausgänge

Idempotency-Key ist Pflicht bei POST und DELETE und gilt 24 Stunden je Schlüssel, Methode und Route. Gespeichert werden nur Status und Ressourcen-IDs, kein Antwortkörper.

201Erster AufrufBodo führt aus und speichert Status und IDs.
201 · ReplayGleicher Key, gleicher BodyDie Antwort wird unter deinem aktuellen Scope neu gerendert, mit Idempotent-Replayed: true.
409Der erste Aufruf läuft nochKurz warten und mit demselben Key wiederholen.IDEMPOTENCY_IN_PROGRESS
422Gleicher Key, anderer BodyBodo führt nichts aus. Für einen neuen Vorgang einen neuen Key erzeugen.IDEMPOTENCY_PAYLOAD_MISMATCH

Antworten mit 5xx, 429 und 503 werden nie gespeichert. Du kannst mit demselben Key einfach wiederholen.

Revision statt Überschreiben

Kontakte, Firmen, Aufgaben und Dokumente tragen eine Revision. Der ETag lautet "r<revision>", If-Match ist optional. Der Vergleich läuft atomar in der Datenbank, nicht im Gateway.

Zwei Schreiber, eine Revision

GET /v1/contacts/con_4Nf7…        → 200, ETag: "r3"

PATCH /v1/contacts/con_4Nf7…
If-Match: "r3"
Content-Type: application/merge-patch+json
{"email": "e.mustermann@musterfirma.de"}
                                  → 200, ETag: "r4"

PATCH … If-Match: "r3"            → 412 PRECONDITION_FAILED

Bei PRECONDITION_FAILED liest du den Datensatz neu, führst deine Änderung darauf zusammen und sendest mit dem neuen ETag.

PATCH nach JSON Merge Patch

RFC 7396, mit Content-Type: application/merge-patch+json.

Du sendest	Wirkung
Feld mit Wert	setzt den Wert
Feld mit `null`	löscht den Wert
Array	ersetzt das ganze Array
Feld fehlt	bleibt unverändert