Zum Hauptinhalt springen

Schreibvorgänge, die eine bestehende Ressource ändern

Es ist kein Header erforderlich. Wo eine Wiederholung früher einen Fehler zurückgab, liefert sie jetzt den aktuellen Zustand: Eine Wiederholung schreibt nichts, und die Antwort enthält Idempotent-Replayed: true – an diesem Header unterscheidest du „Ich habe es storniert“ von „es war bereits storniert“. Drei Ausnahmen liefern stattdessen 409:
  • Aktivieren mit einem anderen activated_at. Der Probenahmezeitpunkt steht im Laborbericht, daher darf ein erneuter Versuch ihn nicht stillschweigend überschreiben.
  • Stornieren eines bereits stornierten Termins mit einem anderen cancellation_reason. Derselbe Grund: Der gespeicherte Grund kann inzwischen korrigiert worden sein, und ein erneuter Versuch darf ihn nicht überschreiben. Sende den gespeicherten Grund erneut mit oder lass ihn weg.
  • Stornieren, wenn es kein Zurück mehr gibt – eine bestätigte Blutabnahme, eine abgeholte Sendung, ein versendetes oder aktiviertes Kit.
Drei Endpunkte sind bewusst nicht wiederholungssicher:

Schreibvorgänge, die etwas erstellen

Fünf Endpunkte akzeptieren einen optionalen Idempotency-Key-Header mit maximal 255 Zeichen: Ein Schlüssel, vier Versuche, eine Bestellung – was du zurückbekommst, hängt davon ab, wann du es erneut versuchst und ob der Body übereinstimmt: Sequenzdiagramm: Ein Duplikat, das 350 ms nach der ersten Anfrage gesendet wird, erhält 409, solange diese Anfrage noch läuft, die erste liefert 201, ein späterer erneuter Versuch mit demselben Schlüssel liefert dieselbe Bestellung mit der Kennzeichnung Idempotent-Replayed, und derselbe Schlüssel mit geändertem Body liefert 409. Sequenzdiagramm: Ein Duplikat, das 350 ms nach der ersten Anfrage gesendet wird, erhält 409, solange diese Anfrage noch läuft, die erste liefert 201, ein späterer erneuter Versuch mit demselben Schlüssel liefert dieselbe Bestellung mit der Kennzeichnung Idempotent-Replayed, und derselbe Schlüssel mit geändertem Body liefert 409. Schlüssel gelten jeweils für deinen API-Schlüssel und den Endpunkt, sodass sie weder mit denen anderer Partner noch mit demselben Schlüssel an anderer Stelle kollidieren.
  • Gleicher Schlüssel, gleicher Body → 24 Stunden lang bekommst du die ursprüngliche Antwort zurück, markiert mit Idempotent-Replayed: true. Feldreihenfolge und Leerzeichen spielen keine Rolle.
  • Gleicher Schlüssel, anderer Body → 409.
  • Ein leerer Idempotency-Key → 400, statt ignoriert zu werden.

Wann der Schlüssel freigegeben wird

Die Erstellung ist nicht atomar – ein 5xx bedeutet nicht, dass nichts geschrieben wurde.
  • Die Anfrage ist fehlgeschlagen, bevor etwas erstellt wurde → der Schlüssel wird freigegeben, sodass du es damit erneut versuchen kannst.
  • Die Anfrage ist fehlgeschlagen, nachdem etwas erstellt wurde, oder hat gar keine Antwort geliefert → der Schlüssel bleibt belegt und erneute Versuche erhalten 409. Ruf die Ressource ab, um zu prüfen, ob sie existiert, und verwende einen neuen Schlüssel, falls nicht.
Eine Wiederholung liefert den Antwort-Body zurück, der beim Erstellen der Ressource gespeichert wurde – einen Snapshot, keinen aktuellen Stand. Wenn sich die Ressource inzwischen geändert hat, ruf sie direkt ab.

Einige Erstellungen haben auch einen natürlichen Schlüssel

Zwei Endpunkte lehnen Duplikate von sich aus ab, unabhängig von jedem Header:
  • Termin erstellen erlaubt einen Termin pro Profil, Standort und Zeitpunkt. Eine Wiederholung liefert 409 mit der bestehenden appointment_id.
  • Profil erstellen liefert 409, wenn für email bereits ein Profil existiert. Lässt du email weg, wird pro Anfrage ein eindeutiger Platzhalter erzeugt, sodass Wiederholungen tatsächlich getrennte Profile erstellen.
Wenn beides zutrifft, erhältst du das 409 des natürlichen Schlüssels, und nur dieses enthält das Zusatzfeld (appointment_id oder einen error_name-Diskriminator) – ein Idempotenz-409 enthält nur error, lies diese Felder also defensiv aus.