Skrivoperationer som ändrar en befintlig resurs
Ingen header behövs. Där en upprepning tidigare returnerade ett fel returnerar den nu aktuellt tillstånd:
En upprepning skriver ingenting, och svaret innehåller
Idempotent-Replayed: true – den headern hjälper dig att skilja mellan “jag avbröt den” och “den var redan avbruten”.
Tre undantag returnerar 409 i stället:
- Aktivera med en annan
activated_at. Provtagningstiden är det som står på labbrapporten, så ett nytt försök får inte skriva över den i tysthet. - Avboka en redan avbokad bokning med en annan
cancellation_reason. Samma resonemang: den registrerade orsaken kan ha korrigerats sedan dess, och ett nytt försök får inte skriva över den. Skicka den registrerade orsaken igen, eller utelämna den. - Avbryta när det är för sent – en bekräftad blodprovstagning, en upphämtad försändelse, ett skickat eller aktiverat kit.
- Bekräfta blodprovstagning – ett andra anrop returnerar
409. - Mejla resultat (
POST /v1/appointments/{id}/results/email) och Mejla resultat (POST /v1/home-kit-orders/{id}/results/email) – varje anrop skickar ett mejl. Ett nytt försök efter en timeout eller5xxkan skicka en dubblett till kunden.
Skrivoperationer som skapar något
Fem slutpunkter accepterar en valfriIdempotency-Key-header, högst 255 tecken:
En nyckel, fyra försök, en beställning – vad du får tillbaka beror på när du försöker igen och om bodyn matchar:
- Samma nyckel, samma body → i 24 timmar får du tillbaka det ursprungliga svaret, märkt
Idempotent-Replayed: true. Fältordning och blanksteg spelar ingen roll. - Samma nyckel, annan body →
409. - En tom
Idempotency-Key→400, i stället för att ignoreras.
När nyckeln frigörs
Skapandet är inte atomärt – ett5xx-svar betyder inte att ingenting skrevs.
- Begäran misslyckades innan något skapades → nyckeln frigörs, så du kan försöka igen med den.
- Begäran misslyckades efter att något skapats, eller gav aldrig något svar → nyckeln förblir upptagen och nya försök får
409. Hämta resursen för att kontrollera om den finns, och använd sedan en ny nyckel om den inte gör det.
En upprepning returnerar svarsbodyn som sparades när resursen skapades – en ögonblicksbild, inte
en aktuell läsning. Om resursen har ändrats sedan dess, hämta den direkt.
Vissa skapandeanrop har också en naturlig nyckel
Två slutpunkter avvisar dubbletter på egen hand, oberoende av eventuella headers:- Skapa bokning tillåter en bokning per profil, plats och tidpunkt. En upprepning returnerar
409med befintligtappointment_id. - Skapa profil returnerar
409näremailredan har en profil. Om du utelämnaremailgenereras en unik platshållare per begäran, så upprepningar skapar separata profiler.
409 från den naturliga nyckeln du får, och bara den innehåller det extra fältet (appointment_id eller en error_name-diskriminator) – en 409 från idempotens innehåller enbart error, så läs dessa fält defensivt.