Zápisy, které mění existující zdroj
Žádná hlavička se nepoužívá. Tam, kde opakované volání dříve vracelo chybu, teď vrací aktuální stav:
Opakované volání nic nezapíše a v odpovědi je hlavička
Idempotent-Replayed: true — podle ní odlišíš „zrušil jsem to“ od „už to bylo zrušené“.
Tři výjimky místo toho vrací 409:
- Aktivace s jiným
activated_at. Čas odběru se propisuje do laboratorní zprávy, takže ho opakovaný pokus nesmí tiše přepsat. - Zrušení už zrušeného termínu s jiným
cancellation_reason. Stejná logika: zaznamenaný důvod mohl být mezitím opravený a opakovaný pokus ho nesmí přepsat. Pošli znovu zaznamenaný důvod, nebo ho vynech. - Zrušení, když už není cesty zpět — potvrzený odběr krve, vyzvednutá zásilka, odeslaná nebo aktivovaná sada.
- Potvrdit odběr krve — druhé volání vrátí
409. - Poslat výsledky e-mailem (
POST /v1/appointments/{id}/results/email) a Poslat výsledky e-mailem (POST /v1/home-kit-orders/{id}/results/email) — každé volání odešle jeden e-mail. Opakování po timeoutu nebo chybě5xxmůže zákazníkovi poslat duplikát.
Zápisy, které něco vytvářejí
Pět endpointů přijímá volitelnou hlavičkuIdempotency-Key o délce nejvýše 255 znaků:
- Vytvořit profil
- Vytvořit termín
- Vytvořit objednávku domácí testovací sady
- Vytvořit zásilku
- Nahrát dokument
- Stejný klíč, stejné tělo → po dobu 24 hodin dostaneš zpět původní odpověď označenou
Idempotent-Replayed: true. Na pořadí polí a bílých znacích nezáleží. - Stejný klíč, jiné tělo →
409. - Prázdný
Idempotency-Key→400, místo aby se ignoroval.
Kdy se klíč uvolní
Vytváření není atomické — chyba5xx neznamená, že se nic nezapsalo.
- Požadavek selhal dřív, než se něco vytvořilo → klíč se uvolní, takže pod ním můžeš pokus zopakovat.
- Požadavek selhal až poté, co se něco vytvořilo, nebo se vůbec nevrátil → klíč zůstane obsazený a opakované pokusy dostanou
409. Načti zdroj a ověř, jestli existuje; pokud ne, použij nový klíč.
Opakování vrátí tělo odpovědi zaznamenané při vytvoření zdroje — jde o snímek z té doby, ne o
aktuální stav. Pokud se zdroj mezitím změnil, načti ho přímo.
Některé vytvářecí operace mají i přirozený klíč
Dva endpointy odmítají duplikáty samy o sobě, nezávisle na jakékoli hlavičce:- Vytvořit termín povoluje jeden termín na profil, odběrové místo a čas. Opakování vrátí
409s existujícímappointment_id. - Vytvořit profil vrátí
409, když pro danýemailuž profil existuje. Pokudemailvynecháš, vygeneruje se pro každý požadavek unikátní zástupná hodnota, takže opakování samostatné profily vytvoří.
409 z přirozeného klíče a jen to obsahuje pole navíc (appointment_id nebo rozlišovač error_name) — 409 z idempotence obsahuje jen error, takže tato pole čti defenzivně.