Hoppa till huvudinnehåll

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.
Tre slutpunkter är avsiktligt inte säkra för nya försök:
  • 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 eller 5xx kan skicka en dubblett till kunden.

Skrivoperationer som skapar något

Fem slutpunkter accepterar en valfri Idempotency-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: Sekvensdiagram: en dubblett som skickas 350 ms efter den första begäran får svaret 409 medan den begäran fortfarande pågår, den första returnerar 201, ett senare nytt försök med samma nyckel returnerar samma beställning märkt Idempotent-Replayed, och samma nyckel med en ändrad body returnerar 409. Sekvensdiagram: en dubblett som skickas 350 ms efter den första begäran får svaret 409 medan den begäran fortfarande pågår, den första returnerar 201, ett senare nytt försök med samma nyckel returnerar samma beställning märkt Idempotent-Replayed, och samma nyckel med en ändrad body returnerar 409. Nycklar är begränsade till din API-nyckel och till slutpunkten, så de krockar aldrig med en annan partners nycklar eller med samma nyckel som används på annat håll.
  • 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 – ett 5xx-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 409 med befintligt appointment_id.
  • Skapa profil returnerar 409 när email redan har en profil. Om du utelämnar email genereras en unik platshållare per begäran, så upprepningar skapar separata profiler.
När båda gäller är det 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.