Spring til hovedindhold

Skrivekald, der ændrer en eksisterende ressource

Ingen header er involveret. Hvor en gentagelse tidligere returnerede en fejl, returnerer den nu den aktuelle tilstand: En gentagelse skriver intet, og dens svar har Idempotent-Replayed: true — med den header kan du skelne mellem “jeg annullerede den” og “den var allerede annulleret”. Tre undtagelser returnerer 409 i stedet:
  • Aktivering med en anden activated_at. Prøvetagningstidspunktet fremgår af laboratorierapporten, så et nyt forsøg må ikke overskrive det i stilhed.
  • Annullering af en allerede annulleret tid med en anden cancellation_reason. Samme begrundelse: Den registrerede årsag kan siden være blevet rettet, og et nyt forsøg må ikke overskrive den. Send den registrerede årsag igen, eller udelad den.
  • Annullering, når det er for sent — en bekræftet blodprøvetagning, en afhentet forsendelse, et afsendt eller aktiveret kit.
Tre endpoints er bevidst ikke sikre ved gentagne forsøg:

Skrivekald, der opretter noget

Fem endpoints accepterer en valgfri Idempotency-Key-header på højst 255 tegn: Én nøgle, fire forsøg, én ordre — hvad du får tilbage, afhænger af, hvornår du prøver igen, og om body matcher: Sekvensdiagram: En dublet sendt 350 ms efter den første forespørgsel får 409, mens den første stadig kører, den første returnerer 201, et senere forsøg med samme nøgle returnerer samme ordre markeret med Idempotent-Replayed, og samme nøgle med en ændret body returnerer 409. Sekvensdiagram: En dublet sendt 350 ms efter den første forespørgsel får 409, mens den første stadig kører, den første returnerer 201, et senere forsøg med samme nøgle returnerer samme ordre markeret med Idempotent-Replayed, og samme nøgle med en ændret body returnerer 409. Nøgler er knyttet til din API-nøgle og til endpointet, så de aldrig kolliderer med en anden partners eller med samme nøgle brugt et andet sted.
  • Samme nøgle, samme body → i 24 timer får du det oprindelige svar tilbage, markeret med Idempotent-Replayed: true. Feltrækkefølge og whitespace har ingen betydning.
  • Samme nøgle, anden body → 409.
  • En tom Idempotency-Key → 400 i stedet for at blive ignoreret.

Hvornår nøglen frigives

Oprettelse er ikke atomisk — en 5xx betyder ikke, at der ikke blev skrevet noget.
  • Forespørgslen fejlede, før noget blev oprettet → nøglen frigives, så du kan prøve igen med den.
  • Forespørgslen fejlede, efter noget var oprettet, eller returnerede aldrig et svar → nøglen forbliver optaget, og nye forsøg får 409. Hent ressourcen for at tjekke, om den findes, og brug derefter en ny nøgle, hvis den ikke gør.
En gentagelse returnerer den response-body, der blev gemt, da ressourcen blev oprettet — et øjebliksbillede, ikke et live-opslag. Hvis ressourcen er ændret siden, skal du hente den direkte.

Nogle oprettelser har også en naturlig nøgle

To endpoints afviser dubletter af sig selv, uafhængigt af nogen header:
  • Opret tid tillader én tid pr. profil, lokation og tidspunkt. En gentagelse returnerer 409 med det eksisterende appointment_id.
  • Opret profil returnerer 409, når email allerede har en profil. Udelader du email, genereres en unik pladsholder pr. forespørgsel, så gentagelser faktisk opretter separate profiler.
Når begge gør sig gældende, er det 409 fra den naturlige nøgle, du ser, og kun den indeholder ekstrafeltet (appointment_id eller en error_name-diskriminator) — en 409 fra idempotens indeholder kun error, så læs disse felter defensivt.