Saltar al contingut principal

Escriptures que modifiquen un recurs existent

No intervé cap capçalera. Allà on una repetició abans retornava un error, ara retorna l’estat actual: Una repetició no escriu res, i la seva resposta porta Idempotent-Replayed: true — aquesta capçalera et permet distingir “l’he cancel·lat jo” de “ja estava cancel·lat”. En canvi, tres excepcions retornen 409:
  • Activar amb un activated_at diferent. L’hora de recollida és la que apareix a l’informe del laboratori, així que un reintent no l’ha de sobreescriure silenciosament.
  • Cancel·lar una cita ja cancel·lada amb un cancellation_reason diferent. El mateix raonament: el motiu registrat pot haver estat corregit mentrestant, i un reintent no l’ha de sobreescriure. Torna a enviar el motiu registrat o omet-lo.
  • Cancel·lar després del punt de no retorn — una extracció de sang confirmada, un enviament recollit, un kit expedit o activat.
Hi ha tres endpoints que deliberadament no són segurs per a reintents:

Escriptures que creen alguna cosa

Cinc endpoints accepten una capçalera opcional Idempotency-Key, de com a màxim 255 caràcters: Una clau, quatre intents, una comanda — el que reps depèn de quan facis el reintent i de si el cos coincideix: Diagrama de seqüència: un duplicat enviat 350 ms després de la primera sol·licitud rep un 409 mentre aquesta sol·licitud encara està en curs, la primera retorna 201, un reintent posterior amb la mateixa clau retorna la mateixa comanda marcada com a Idempotent-Replayed, i la mateixa clau amb un cos modificat retorna 409. Diagrama de seqüència: un duplicat enviat 350 ms després de la primera sol·licitud rep un 409 mentre aquesta sol·licitud encara està en curs, la primera retorna 201, un reintent posterior amb la mateixa clau retorna la mateixa comanda marcada com a Idempotent-Replayed, i la mateixa clau amb un cos modificat retorna 409. Les claus estan limitades a la teva clau d’API i a l’endpoint, així que no col·lideixen mai amb les d’un altre soci ni amb la mateixa clau feta servir en un altre lloc.
  • Mateixa clau, mateix cos → durant 24 hores reps la resposta original, marcada amb Idempotent-Replayed: true. L’ordre dels camps i els espais en blanc no importen.
  • Mateixa clau, cos diferent → 409.
  • Una Idempotency-Key buida → 400, en lloc d’ignorar-se.

Quan s’allibera la clau

La creació no és atòmica — un 5xx no vol dir que no s’hagi escrit res.
  • La sol·licitud ha fallat abans de crear res → la clau s’allibera, així que pots tornar-ho a intentar amb la mateixa clau.
  • La sol·licitud ha fallat després de crear alguna cosa, o no ha retornat cap resposta → la clau continua reservada i els reintents reben 409. Consulta el recurs per comprovar si existeix i, si no existeix, fes servir una clau nova.
Una repetició retorna el cos de la resposta registrat quan es va crear el recurs — una instantània, no una lectura en temps real. Si el recurs ha canviat des de llavors, consulta’l directament.

Algunes creacions també tenen una clau natural

Dos endpoints rebutgen duplicats per si sols, independentment de qualsevol capçalera:
  • Crea una cita permet una cita per perfil, ubicació i instant. Una repetició retorna 409 amb l’appointment_id existent.
  • Crea un perfil retorna 409 quan email ja té un perfil. Si omets email, es genera un valor provisional únic per sol·licitud, així que les repeticions sí que creen perfils separats.
Quan s’apliquen totes dues, veuràs el 409 de la clau natural, i només aquest inclou el camp addicional (appointment_id, o un discriminador error_name) — un 409 d’idempotència només porta error, així que llegeix aquests camps de manera defensiva.