Operații de scriere care modifică o resursă existentă
Nu este implicat niciun header. Acolo unde o repetare returna anterior o eroare, acum returnează starea curentă:
O repetare nu scrie nimic, iar răspunsul ei conține
Idempotent-Replayed: true — prin acel header faci diferența între „am anulat-o eu” și „era deja anulată”.
Trei excepții returnează în schimb 409:
- Activarea cu un
activated_atdiferit. Momentul recoltării apare pe raportul de laborator, așa că o reîncercare nu trebuie să îl suprascrie silențios. - Anularea unei programări deja anulate cu un
cancellation_reasondiferit. Același raționament: motivul înregistrat poate să fi fost corectat între timp, iar o reîncercare nu trebuie să îl suprascrie. Retrimite motivul înregistrat sau omite-l. - Anularea după punctul fără întoarcere — o recoltare de sânge confirmată, o expediere preluată, un kit expediat sau activat.
- Confirmă recoltarea de sânge — un al doilea apel returnează
409. - Trimite rezultatele pe e-mail (
POST /v1/appointments/{id}/results/email) și Trimite rezultatele pe e-mail (POST /v1/home-kit-orders/{id}/results/email) — fiecare apel trimite un e-mail. O reîncercare după un timeout sau un5xxpoate trimite clientului un duplicat.
Operații de scriere care creează ceva
Cinci endpoint-uri acceptă un header opționalIdempotency-Key, de cel mult 255 de caractere:
- Creează profil
- Creează programare
- Creează comandă de kit de testare la domiciliu
- Creează expediere
- Încarcă document
- Aceeași cheie, același corp → timp de 24 de ore primești înapoi răspunsul original, marcat cu
Idempotent-Replayed: true. Ordinea câmpurilor și spațiile albe nu contează. - Aceeași cheie, corp diferit →
409. - Un
Idempotency-Keygol →400, în loc să fie ignorat.
Când este eliberată cheia
Crearea nu este atomică — un5xx nu înseamnă că nu s-a scris nimic.
- Cererea a eșuat înainte să se creeze ceva → cheia este eliberată, așa că poți reîncerca folosind-o.
- Cererea a eșuat după ce s-a creat ceva sau nu a returnat deloc un răspuns → cheia rămâne rezervată, iar reîncercările primesc
409. Preia resursa pentru a verifica dacă există, apoi folosește o cheie nouă dacă nu există.
O reluare returnează corpul răspunsului înregistrat la crearea resursei — un snapshot, nu o citire
în timp real. Dacă resursa s-a modificat între timp, preia-o direct.
Unele operații de creare au și o cheie naturală
Două endpoint-uri resping duplicatele de la sine, independent de orice header:- Creează programare permite o singură programare per profil, locație și moment. O repetare returnează
409cuappointment_id-ul existent. - Creează profil returnează
409cândemailare deja un profil. Dacă omițiemail, se generează un placeholder unic pentru fiecare cerere, așa că repetările chiar creează profiluri separate.
409 al cheii naturale și doar acesta conține câmpul suplimentar (appointment_id sau un discriminator error_name) — un 409 de idempotență conține doar error, așa că citește acele câmpuri defensiv.