Operacje zapisu, które zmieniają istniejący zasób
Nie jest tu potrzebny żaden nagłówek. Tam, gdzie powtórzenie wcześniej zwracało błąd, teraz zwraca bieżący stan:
Powtórzenie niczego nie zapisuje, a odpowiedź zawiera nagłówek
Idempotent-Replayed: true — dzięki niemu odróżnisz „anulowano teraz” od „było już anulowane”.
Trzy wyjątki zwracają zamiast tego 409:
- Aktywacja z innym
activated_at. Czas pobrania trafia na raport laboratoryjny, więc ponowna próba nie może go po cichu nadpisać. - Anulowanie już anulowanej wizyty z innym
cancellation_reason. Ten sam powód: zapisana przyczyna mogła zostać w międzyczasie poprawiona i ponowna próba nie może jej nadpisać. Wyślij ponownie zapisaną przyczynę albo ją pomiń. - Anulowanie po punkcie bez powrotu — potwierdzone pobranie krwi, odebrana przesyłka, wysłany lub aktywowany zestaw.
- Potwierdź pobranie krwi — drugie wywołanie zwraca
409. - Wyślij wyniki e-mailem (
POST /v1/appointments/{id}/results/email) oraz Wyślij wyniki e-mailem (POST /v1/home-kit-orders/{id}/results/email) — każde wywołanie wysyła jednego e-maila. Ponowna próba po przekroczeniu czasu oczekiwania lub błędzie5xxmoże wysłać klientowi duplikat.
Operacje zapisu, które coś tworzą
Pięć endpointów akceptuje opcjonalny nagłówekIdempotency-Key o długości maksymalnie 255 znaków:
- Utwórz profil
- Utwórz wizytę
- Utwórz zamówienie domowego zestawu testowego
- Utwórz przesyłkę
- Prześlij dokument
- Ten sam klucz, ta sama treść → przez 24 godziny otrzymujesz pierwotną odpowiedź oznaczoną
Idempotent-Replayed: true. Kolejność pól i białe znaki nie mają znaczenia. - Ten sam klucz, inna treść →
409. - Pusty
Idempotency-Key→400zamiast zignorowania.
Kiedy klucz jest zwalniany
Tworzenie nie jest atomowe — błąd5xx nie oznacza, że nic nie zostało zapisane.
- Żądanie nie powiodło się, zanim cokolwiek utworzono → klucz jest zwalniany, więc możesz ponowić próbę z tym samym kluczem.
- Żądanie nie powiodło się po tym, jak coś utworzono, lub w ogóle nie zwróciło odpowiedzi → klucz pozostaje zajęty, a ponowne próby zwracają
409. Pobierz zasób, aby sprawdzić, czy istnieje, a jeśli nie, użyj nowego klucza.
Powtórzenie zwraca treść odpowiedzi zapisaną w momencie utworzenia zasobu — migawkę, a nie bieżący
odczyt. Jeśli zasób od tego czasu się zmienił, pobierz go bezpośrednio.
Niektóre operacje tworzenia mają też klucz naturalny
Dwa endpointy odrzucają duplikaty samodzielnie, niezależnie od nagłówka:- Utwórz wizytę pozwala na jedną wizytę dla danego profilu, lokalizacji i terminu. Powtórzenie zwraca
409z istniejącymappointment_id. - Utwórz profil zwraca
409, gdy dlaemailistnieje już profil. Jeśli pominieszemail, dla każdego żądania generowana jest unikalna wartość zastępcza, więc powtórzenia faktycznie tworzą osobne profile.
409 z klucza naturalnego i tylko ta odpowiedź zawiera dodatkowe pole (appointment_id lub wyróżnik error_name) — 409 z idempotentności zawiera wyłącznie error, więc odczytuj te pola defensywnie.