Idempotence et suivi du dépôt

Une clé d’idempotence associe plusieurs tentatives HTTP à une seule opération logique de dépôt. Elle évite de rappeler les prestataires de preuve lors d’une reprise identique déjà connue. Elle est facultative dans le protocole et recommandée pour une intégration fiable.

Conserver une clé par opération

Générez une valeur unique, par exemple un UUID, et enregistrez-la durablement avant le premier envoi. Transmettez-la dans l’en-tête Idempotency-Key ; la longueur maximale est de 191 caractères. La portée est l’organisation authentifiée.

La requête est associée à une empreinte qui inclut le contenu et ses paramètres : nom, type de média, référence métier, espace, durée, métadonnées, attributs de recherche, contrôle d’empreinte et politique de signature. Une même clé avec un autre contenu ou d’autres paramètres produit 409.

Interpréter les états

stateDiagram-v2
  [*] --> processing: Clé réservée
  processing --> succeeded: Dépôt enregistré
  processing --> failed: Échec ou bail expiré
  succeeded --> succeeded: Reprise identique
  failed --> failed: Reprise identique

État connu	Reprise du POST identique	Action du client
`processing`	`202` et `Retry-After`	Attendre puis consulter le statut
`succeeded`	`200` et l’objet existant	Enregistrer ou confirmer l’UUID
`failed`	`409`, sans nouvelle exécution	Examiner l’échec ; une nouvelle tentative logique exige une nouvelle clé
Clé déjà utilisée avec une autre empreinte	`409`	Corriger la correspondance clé/requête
Dépôt réussi dont l’objet n’est plus disponible	`410` lors de la reprise	Ne pas recréer automatiquement le document

Les états terminaux ne sont pas réouverts. La protection porte sur le dépôt CCFN ; elle ne constitue pas une transaction distribuée qui annulerait un appel déjà réalisé chez un prestataire externe.

Consulter le statut après une coupure réseau

curl --user "$CCFN_USER" \
  -H "Idempotency-Key: $(cat depot.key)" \
  "$CCFN_BASE_URL/api/ccfn/v1/object/deposit/status"

Ce GET nécessite le même droit de dépôt. 202 désigne un état encore en cours. Un état terminal connu est retourné avec 200 : contrôlez data.status, car ce code ne signifie pas nécessairement que le dépôt a réussi. Une clé inconnue retourne 404 et data.status="unknown".

Une réponse de suivi contient notamment status, object_id, failure_code, processing_expires_at, created_at, updated_at et retry_after. object_id peut être nul tant que le dépôt n’a pas abouti.

Traitements abandonnés

Le bail de traitement est de 900 secondes par défaut et est renouvelé autour des opérations longues. Un traitement dont le bail expire est marqué failed, avec failure_code="processing_abandoned". Il n’est pas repris avec la même clé, car le service ne peut pas établir qu’un appel externe interrompu n’a pas déjà été exécuté.

Retry-After, de 5 secondes par défaut, indique un délai de consultation. Ce n’est pas une estimation de la durée restante. Évitez les boucles de consultation sans limite et conservez les états pour permettre une reprise opérateur.

Règle de reprise

Après une erreur réseau ou une réponse technique ambiguë, consultez l’état avec la clé d’origine. Si la clé est inconnue, vous pouvez réémettre la même opération avec la même clé. Si elle est en cours, attendez. Si elle a réussi, récupérez l’objet. Si elle a échoué, analysez la cause avant de décider d’une nouvelle opération avec une nouvelle clé.

À lire ensuite : Erreurs et supervision, Exemples d’intégration.