Hopp til hovedinnhold

Skriveoperasjoner som endrer en eksisterende ressurs

Ingen header er involvert. Der en gjentakelse tidligere returnerte en feil, returnerer den nå gjeldende tilstand: En gjentakelse skriver ingenting, og svaret inneholder Idempotent-Replayed: true — denne headeren lar deg skille mellom «jeg kansellerte den» og «den var allerede kansellert». Tre unntak returnerer 409 i stedet:
  • Aktivering med et annet activated_at. Prøvetakingstidspunktet står i laboratorierapporten, så et nytt forsøk må ikke overskrive det i stillhet.
  • Kansellering av en allerede kansellert time med en annen cancellation_reason. Samme logikk: den registrerte årsaken kan ha blitt rettet i ettertid, og et nytt forsøk må ikke overskrive den. Send den registrerte årsaken på nytt, eller utelat den.
  • Kansellering når det ikke lenger kan gjøres om — en bekreftet blodprøvetaking, en hentet forsendelse, et sendt eller aktivert sett.
Tre endepunkter er bevisst ikke trygge å prøve på nytt:

Skriveoperasjoner som oppretter noe

Fem endepunkter godtar en valgfri Idempotency-Key-header på maksimalt 255 tegn: Én nøkkel, fire forsøk, én bestilling — hva du får tilbake avhenger av når du prøver på nytt og om innholdet samsvarer: Sekvensdiagram: et duplikat som sendes 350 ms etter den første forespørselen får 409 mens den første fortsatt kjører, den første returnerer 201, et senere nytt forsøk med samme nøkkel returnerer den samme bestillingen merket Idempotent-Replayed, og samme nøkkel med endret innhold returnerer 409. Sekvensdiagram: et duplikat som sendes 350 ms etter den første forespørselen får 409 mens den første fortsatt kjører, den første returnerer 201, et senere nytt forsøk med samme nøkkel returnerer den samme bestillingen merket Idempotent-Replayed, og samme nøkkel med endret innhold returnerer 409. Nøkler er begrenset til API-nøkkelen din og til endepunktet, så de kolliderer aldri med en annen partners nøkler eller med samme nøkkel brukt et annet sted.
  • Samme nøkkel, samme innhold → i 24 timer får du det opprinnelige svaret tilbake, merket Idempotent-Replayed: true. Rekkefølgen på feltene og blanktegn har ingen betydning.
  • Samme nøkkel, annet innhold → 409.
  • En tom Idempotency-Key → 400, i stedet for å bli ignorert.

Når nøkkelen frigis

Opprettelse er ikke atomær — en 5xx betyr ikke at ingenting ble skrevet.
  • Forespørselen feilet før noe ble opprettet → nøkkelen frigis, så du kan prøve på nytt med den.
  • Forespørselen feilet etter at noe ble opprettet, eller returnerte aldri → nøkkelen forblir opptatt, og nye forsøk får 409. Hent ressursen for å sjekke om den finnes, og bruk deretter en ny nøkkel hvis den ikke gjør det.
En gjentakelse returnerer svarinnholdet som ble registrert da ressursen ble opprettet — et øyeblikksbilde, ikke en sanntidslesing. Hvis ressursen har endret seg siden da, henter du den direkte.

Noen opprettelser har også en naturlig nøkkel

To endepunkter avviser duplikater på egen hånd, uavhengig av eventuell header:
  • Opprett time tillater én time per profil, lokasjon og tidspunkt. En gjentakelse returnerer 409 med eksisterende appointment_id.
  • Opprett profil returnerer 409 når email allerede har en profil. Utelater du email, genereres en unik plassholder per forespørsel, så gjentakelser oppretter faktisk separate profiler.
Når begge gjelder, er det 409 fra den naturlige nøkkelen du får, og bare den inneholder ekstrafeltet (appointment_id, eller en error_name-diskriminator) — en 409 fra idempotens inneholder bare error, så les disse feltene defensivt.