Écritures qui modifient une ressource existante
Aucun en-tête n’est requis. Là où une répétition renvoyait auparavant une erreur, elle renvoie désormais l’état actuel :
Une répétition n’écrit rien et sa réponse contient
Idempotent-Replayed: true — c’est cet en-tête qui te permet de distinguer « je l’ai annulé » de « c’était déjà annulé ».
Trois exceptions renvoient 409 à la place :
- Activer avec un
activated_atdifférent. L’heure de prélèvement figure sur le rapport de laboratoire, une nouvelle tentative ne doit donc pas l’écraser silencieusement. - Annuler un rendez-vous déjà annulé avec un
cancellation_reasondifférent. Même logique : le motif enregistré peut avoir été corrigé depuis, et une nouvelle tentative ne doit pas l’écraser. Renvoie le motif enregistré ou omets-le. - Annuler après le point de non-retour — une prise de sang confirmée, un envoi collecté, un kit expédié ou activé.
- Confirmer une prise de sang — un deuxième appel renvoie
409. - Envoyer les résultats par e-mail (
POST /v1/appointments/{id}/results/email) et Envoyer les résultats par e-mail (POST /v1/home-kit-orders/{id}/results/email) — chaque appel envoie un e-mail. Une nouvelle tentative après un timeout ou une erreur5xxpeut envoyer un doublon au client.
Écritures qui créent quelque chose
Cinq endpoints acceptent un en-têteIdempotency-Key optionnel de 255 caractères maximum :
- Créer un profil
- Créer un rendez-vous
- Créer une commande de kit à domicile
- Créer un envoi
- Téléverser un document
- Même clé, même corps → pendant 24 heures, tu reçois la réponse d’origine, marquée
Idempotent-Replayed: true. L’ordre des champs et les espaces n’ont pas d’importance. - Même clé, corps différent →
409. - Un
Idempotency-Keyvide →400, plutôt que d’être ignoré.
Quand la clé est libérée
La création n’est pas atomique — une erreur5xx ne signifie pas que rien n’a été écrit.
- La requête a échoué avant toute création → la clé est libérée, tu peux donc réessayer avec la même clé.
- La requête a échoué après une création, ou n’a jamais renvoyé de réponse → la clé reste réservée et les nouvelles tentatives reçoivent
409. Récupère la ressource pour vérifier si elle existe, puis utilise une nouvelle clé si ce n’est pas le cas.
Un appel rejoué renvoie le corps de réponse enregistré lors de la création de la ressource — un
instantané, pas une lecture en direct. Si la ressource a changé depuis, récupère-la directement.
Certaines créations ont aussi une clé naturelle
Deux endpoints rejettent les doublons d’eux-mêmes, indépendamment de tout en-tête :- Créer un rendez-vous autorise un seul rendez-vous par profil, lieu et horaire. Une répétition renvoie
409avec l’appointment_idexistant. - Créer un profil renvoie
409lorsqueemaila déjà un profil. Ometsemailet une valeur de remplacement unique est générée par requête ; les répétitions créent donc bien des profils distincts.
409 de la clé naturelle qui est renvoyé, et lui seul contient le champ supplémentaire (appointment_id ou un discriminateur error_name) — un 409 d’idempotence ne contient que error, lis donc ces champs de manière défensive.