- Documentation
- API · Version 1.0
- Idempotence
Idempotence
Sur cette page
Le risque central d'une API de publication est de publier deux fois. Un client HTTP qui perd la réponse à un POST retentera, et sans garde la seconde tentative créerait une seconde publication. L'API exige donc une clé d'idempotence sur les écritures qui créent quelque chose.
Où la clé est exigée
L'en-tête Idempotency-Key est obligatoire sur :
POST /publications;POST /media.
Sans lui, la requête est refusée avant toute exécution :
{
"error": {
"code": "idempotency_key_required",
"message": "L'en-tête Idempotency-Key est obligatoire sur cette écriture : sans lui, une requête rejouée après un délai réseau publierait une seconde fois."
}
}
Une clé de plus de 255 caractères reçoit 400 idempotency_key_too_long.
Choisir une clé
Dérivez la clé de ce qui déclenche l'écriture, plutôt que de la tirer au hasard : article-42-publie-v1 se recalcule à l'identique après un redémarrage de votre processus, un UUID tiré à la volée ne se retrouve pas.
Si votre clé naturelle est longue — une URL, un chemin —, hachez-la : 'pub-'.hash('sha256', $url) tient en 68 caractères et reste déterministe.
Une clé n'est jamais partagée entre deux clients d'API : la même valeur employée par deux clients désigne deux requêtes distinctes.
Ce qui se passe à la réception
| Situation | Réponse |
|---|---|
| Clé inconnue | La requête s'exécute. Si elle réussit, sa réponse est conservée. |
| Clé connue, même corps, réponse conservée | La réponse conservée est rendue telle quelle, avec l'en-tête Idempotent-Replay: true. Rien n'est recréé. |
| Clé connue, même corps, requête encore en cours | 409 idempotency_key_in_flight. |
| Clé connue, corps différent | 409 idempotency_key_reused. |
Rendre la ressource d'origine sur un corps différent ferait croire au client que sa nouvelle demande a été prise en compte : c'est pourquoi ce cas est un conflit.
Détails du mécanisme
- Seules les réussites sont conservées. Une réponse d'erreur (statut 400 ou plus) libère la clé : la requête peut être corrigée puis rejouée avec la même clé.
- La clé est réservée avant l'exécution. Deux requêtes concurrentes portant la même clé ne peuvent pas s'exécuter toutes les deux ; la seconde reçoit
409 idempotency_key_in_flight. - Une réservation abandonnée est reprise. Si le processus qui détenait la clé s'est arrêté sans répondre, la réservation est tenue pour perdue au bout de cinq minutes, et la requête suivante portant cette clé s'exécute normalement.
- Une clé vit 24 heures. Passé ce délai, elle est oubliée : la même valeur redevient une clé inconnue. Ne comptez pas sur une clé de plus d'un jour pour empêcher un doublon.
- L'empreinte du corps ignore l'ordre des clés d'un objet, à tous les niveaux :
{"a":1,"b":2}et{"b":2,"a":1}sont le même corps. Les listes, elles, gardent leur ordre :destination_idsdans un autre ordre est un autre corps. - Sur un envoi de fichier, l'empreinte porte sur le contenu (condensat SHA-256), pas sur le nom : renvoyer la même image sous un autre nom est le même envoi.
Les autres écritures
Les transitions — publish, cancel, retry — s'appellent sans clé. Elles sont idempotentes par nature : chacune refuse l'état qu'elle produit, et un second appel répond 409 transition_not_allowed sans rien changer.
Les écritures de webhook n'en exigent pas non plus : déclarer deux fois le même endpoint se voit et se répare, là où publier deux fois ne se répare pas.
Réessayer sans publier deux fois
La règle tient en une ligne : gardez la clé, rejouez la requête.
| Situation | Clé | Corps |
|---|---|---|
| Réseau coupé, aucune réponse | la même | inchangé |
5xx |
la même | inchangé |
429 |
la même | inchangé |
409 idempotency_key_in_flight |
la même, après un court délai | inchangé |
422 |
la même | corrigé |
400 sur la clé |
corrigée | inchangé |
| Contenu volontairement différent | nouvelle | nouveau |
Un rejeu qui rend la réponse conservée porte Idempotent-Replay: true : rien n'a été créé cette fois-ci, ce qui évite de compter deux fois la même publication dans vos propres statistiques.