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.
- Blutabnahme bestätigen – ein zweiter Aufruf liefert
409. - Ergebnisse per E-Mail senden (
POST /v1/appointments/{id}/results/email) und Ergebnisse per E-Mail senden (POST /v1/home-kit-orders/{id}/results/email) – jeder Aufruf verschickt eine E-Mail. Ein erneuter Versuch nach einem Timeout oder5xxkann dem Kunden eine doppelte E-Mail schicken.
Schreibvorgänge, die etwas erstellen
Fünf Endpunkte akzeptieren einen optionalenIdempotency-Key-Header mit maximal 255 Zeichen:
- Profil erstellen
- Termin erstellen
- Heimtest-Kit-Bestellung erstellen
- Sendung erstellen
- Dokument hochladen
- 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 – ein5xx 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
409mit der bestehendenappointment_id. - Profil erstellen liefert
409, wenn füremailbereits ein Profil existiert. Lässt duemailweg, wird pro Anfrage ein eindeutiger Platzhalter erzeugt, sodass Wiederholungen tatsächlich getrennte Profile erstellen.
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.