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_atdiferent. 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_reasondiferent. 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.
- Confirma l’extracció de sang — una segona crida retorna
409. - Envia els resultats per correu electrònic (
POST /v1/appointments/{id}/results/email) i Envia els resultats per correu electrònic (POST /v1/home-kit-orders/{id}/results/email) — cada crida envia un correu electrònic. Un reintent després d’un temps d’espera esgotat o un5xxpot enviar un duplicat al client.
Escriptures que creen alguna cosa
Cinc endpoints accepten una capçalera opcionalIdempotency-Key, de com a màxim 255 caràcters:
- Crea un perfil
- Crea una cita
- Crea una comanda de kit de prova a casa
- Crea un enviament
- Puja un document
- 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-Keybuida →400, en lloc d’ignorar-se.
Quan s’allibera la clau
La creació no és atòmica — un5xx 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
409amb l’appointment_idexistent. - Crea un perfil retorna
409quanemailja té un perfil. Si ometsemail, es genera un valor provisional únic per sol·licitud, així que les repeticions sí que creen perfils separats.
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.