Scritture che modificano una risorsa esistente
Non serve alcun header. Dove prima una ripetizione restituiva un errore, ora restituisce lo stato attuale:
Una ripetizione non scrive nulla e la sua risposta contiene
Idempotent-Replayed: true — quell’header ti permette di distinguere “l’ho annullato io” da “era già annullato”.
Tre eccezioni restituiscono invece 409:
- Attivazione con un
activated_atdiverso. L’orario di raccolta è quello riportato sul referto di laboratorio, quindi un nuovo tentativo non deve sovrascriverlo silenziosamente. - Annullamento di un appuntamento già annullato con un
cancellation_reasondiverso. Stesso ragionamento: il motivo registrato può essere stato corretto nel frattempo e un nuovo tentativo non deve sovrascriverlo. Invia di nuovo il motivo registrato oppure omettilo. - Annullamento oltre il punto di non ritorno — un prelievo di sangue confermato, una spedizione ritirata, un kit spedito o attivato.
- Conferma prelievo di sangue — una seconda chiamata restituisce
409. - Invia risultati via email (
POST /v1/appointments/{id}/results/email) e Invia risultati via email (POST /v1/home-kit-orders/{id}/results/email) — ogni chiamata invia un’email. Un nuovo tentativo dopo un timeout o un5xxpuò inviare un duplicato al cliente.
Scritture che creano qualcosa
Cinque endpoint accettano un headerIdempotency-Key opzionale, di massimo 255 caratteri:
Una chiave, quattro tentativi, un ordine — ciò che ricevi dipende da quando riprovi e se il body corrisponde:
- Stessa chiave, stesso body → per 24 ore ricevi di nuovo la risposta originale, contrassegnata con
Idempotent-Replayed: true. L’ordine dei campi e gli spazi bianchi non contano. - Stessa chiave, body diverso →
409. - Un
Idempotency-Keyvuoto →400, invece di essere ignorato.
Quando la chiave viene rilasciata
La creazione non è atomica — un5xx non significa che non sia stato scritto nulla.
- La richiesta è fallita prima che venisse creato qualcosa → la chiave viene rilasciata, quindi puoi riprovare usandola.
- La richiesta è fallita dopo che è stato creato qualcosa, oppure non ha mai restituito risposta → la chiave resta riservata e i nuovi tentativi ricevono
409. Recupera la risorsa per verificare se esiste, poi usa una nuova chiave in caso contrario.
Una ripetizione restituisce il body della risposta registrato al momento della creazione della
risorsa — uno snapshot, non una lettura in tempo reale. Se la risorsa è cambiata nel frattempo,
recuperala direttamente.
Alcune creazioni hanno anche una chiave naturale
Due endpoint rifiutano i duplicati autonomamente, indipendentemente da qualsiasi header:- Crea appuntamento consente un appuntamento per profilo, sede e istante. Una ripetizione restituisce
409con l’appointment_idesistente. - Crea profilo restituisce
409quandoemailha già un profilo. Se omettiemail, viene generato un segnaposto univoco per ogni richiesta, quindi le ripetizioni creano effettivamente profili separati.
409 della chiave naturale, ed è l’unico a contenere il campo extra (appointment_id, o un discriminatore error_name) — un 409 di idempotenza contiene solo error, quindi leggi questi campi in modo difensivo.