Passer au contenu principal

É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_at diffé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_reason diffé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é.
Trois endpoints ne sont volontairement pas sûrs en cas de nouvelle tentative :

Écritures qui créent quelque chose

Cinq endpoints acceptent un en-tête Idempotency-Key optionnel de 255 caractères maximum : Une clé, quatre tentatives, une commande — ce que tu obtiens dépend du moment où tu réessaies et de la correspondance du corps : Diagramme de séquence : un doublon envoyé 350 ms après la première requête reçoit 409 tant que celle-ci est encore en cours, la première renvoie 201, une nouvelle tentative ultérieure avec la même clé renvoie la même commande marquée Idempotent-Replayed, et la même clé avec un corps modifié renvoie 409. Diagramme de séquence : un doublon envoyé 350 ms après la première requête reçoit 409 tant que celle-ci est encore en cours, la première renvoie 201, une nouvelle tentative ultérieure avec la même clé renvoie la même commande marquée Idempotent-Replayed, et la même clé avec un corps modifié renvoie 409. Les clés sont limitées à ta clé API et à l’endpoint, elles n’entrent donc jamais en collision avec celles d’un autre partenaire ni avec la même clé utilisée ailleurs.
  • 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-Key vide → 400, plutôt que d’être ignoré.

Quand la clé est libérée

La création n’est pas atomique — une erreur 5xx 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 409 avec l’appointment_id existant.
  • Créer un profil renvoie 409 lorsque email a déjà un profil. Omets email et une valeur de remplacement unique est générée par requête ; les répétitions créent donc bien des profils distincts.
Lorsque les deux s’appliquent, c’est le 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.