Vai al contenuto principale

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_at diverso. 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_reason diverso. 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.
Tre endpoint non sono volutamente sicuri in caso di ripetizione:

Scritture che creano qualcosa

Cinque endpoint accettano un header Idempotency-Key opzionale, di massimo 255 caratteri: Una chiave, quattro tentativi, un ordine — ciò che ricevi dipende da quando riprovi e se il body corrisponde: Diagramma di sequenza: un duplicato inviato 350 ms dopo la prima richiesta riceve 409 mentre quella richiesta è ancora in esecuzione, la prima restituisce 201, un tentativo successivo con la stessa chiave restituisce lo stesso ordine contrassegnato come Idempotent-Replayed e la stessa chiave con un body modificato restituisce 409. Diagramma di sequenza: un duplicato inviato 350 ms dopo la prima richiesta riceve 409 mentre quella richiesta è ancora in esecuzione, la prima restituisce 201, un tentativo successivo con la stessa chiave restituisce lo stesso ordine contrassegnato come Idempotent-Replayed e la stessa chiave con un body modificato restituisce 409. Le chiavi sono associate alla tua chiave API e all’endpoint, quindi non entrano mai in conflitto con quelle di un altro partner o con la stessa chiave usata altrove.
  • 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-Key vuoto → 400, invece di essere ignorato.

Quando la chiave viene rilasciata

La creazione non è atomica — un 5xx 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 409 con l’appointment_id esistente.
  • Crea profilo restituisce 409 quando email ha già un profilo. Se ometti email, viene generato un segnaposto univoco per ogni richiesta, quindi le ripetizioni creano effettivamente profili separati.
Quando si applicano entrambi, vedi il 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.