Idempotence

Pourquoi#

Si votre application ne reçoit pas de réponse à un POST, elle ne sait pas s'il est arrivé : la commande a-t-elle été acceptée, la réservation créée ? Sans protection, une nouvelle tentative crée une seconde réservation. Avec une Idempotency-Key, Flavoso répond à la nouvelle tentative avec le résultat de la première.

Fonctionnement#

• Pour un POST, envoyez l'en-tête Idempotency-Key avec une chaîne unique : 1 à 255 caractères ASCII imprimables. Pour PUT, PATCH et DELETE, Flavoso ignore l'en-tête.
• La clé s'applique par connexion. Flavoso conserve la première réponse (statut et corps) pendant 24 heures.
• Si la même requête arrive à nouveau avec la même clé, la première réponse est renvoyée, avec Idempotent-Replayed: true, et rien ne se produit une seconde fois.
• La comparaison porte sur la méthode, le chemin et les octets bruts du corps. Une nouvelle tentative doit donc envoyer exactement le même corps : des espaces différents ou un autre ordre des champs suffisent à en faire une autre requête, et la même clé avec une autre requête renvoie 422 idempotency_key_reused.
• Si la première requête est encore en cours, la seconde reçoit 409 idempotency_in_progress. Patientez un instant, puis réessayez. Si la première n'a jamais abouti (interrompue de notre côté), la clé est libérée au bout de 2 minutes.
• Une réponse 5xx ou 409 conflict n'est pas conservée : la nouvelle tentative est exécutée.

# Create the key ONCE per operation and keep it for every retry of that operation
KEY=$(uuidgen)
curl -X POST https://api.flavoso.com/v1/orders/ORDER_ID/accept \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $KEY"
# No answer? Send exactly the same command again, with the same $KEY.

HTTP/1.1 200 OK
Idempotent-Replayed: true
X-Request-Id: req_9a1b2c3d4e5f60718293a4b5
Content-Type: application/json

{ "object": "order", "id": "cce01f52-5188-410f-9659-6ce26ba9b784", "status": "confirmed", ... }

Choisir de bonnes clés#

La clé est liée à l'opération, pas à la tentative. Créez-la une seule fois, quand votre programme décide d'agir, et réutilisez-la pour chaque nouvelle tentative de cette même opération.

• Dérivée de vos propres données : accept-<id de commande>, ack-<id de commande>, booking-<votre numéro de réservation>.
• Ou un UUID, enregistré avec la tâche dans votre file d'attente.
• Jamais une nouvelle clé à chaque tentative : elle ne protégerait alors de rien.

Ce qui est répétable par nature#

• Les changements de statut : une commande déjà au statut cible est renvoyée inchangée avec 200, et accept renvoie inchangée une commande qui a déjà dépassé pending.
• POST /orders/{id}/acknowledge : une commande prise en charge le reste ; renvoyer le même external_id ne change rien.
• PUT /menu, PUT /store/hours, POST /menu/availability et chaque PATCH : ils fixent un état cible au lieu de basculer. Les envoyer deux fois donne le même résultat qu'une seule.

Pour un POST, une Idempotency-Key ne nuit jamais et garantit en plus une réponse identique ; pour PUT et PATCH, Flavoso l'ignore.