Reprises sûres dans une API de fichiers : éviter les doublons

Le problème : le timeout ne dit pas si l’opération a eu lieu

Le cas dangereux dans une intégration de fichiers n’est pas l’erreur claire, mais la réponse qui n’arrive jamais. Votre backend appelle une API pour créer un dossier, téléverser un fichier, lancer une transformation ou préparer un téléchargement partagé ; la connexion est interrompue par timeout ; et le client ne sait pas si le serveur a exécuté l’action. Si vous répétez simplement l’appel, vous pouvez créer deux dossiers, enregistrer deux copies du même fichier, mettre en file d’attente deux transformations ou publier deux liens équivalents.

La première décision opérationnelle consiste à séparer les lectures des écritures. En HTTP, des méthodes comme GET, HEAD et OPTIONS sont considérées comme sûres, car le client ne demande pas de changement d’état. En revanche, les actions qui créent, modifient, déplacent, suppriment ou mettent du travail en file d’attente doivent être traitées comme des écritures. La RFC 9110 définit une requête idempotente comme une requête dont l’effet prévu, lorsque plusieurs requêtes identiques sont répétées, est le même que lorsqu’elle est exécutée une seule fois ; c’est pourquoi, en cas d’échec de communication, il ne convient de répéter automatiquement que lorsque l’opération est conçue pour le supporter.

• Lectures : consulter des listes, le détail, l’état d’une tâche ou des résultats déjà générés.
• Écritures : créer des dossiers, téléverser des fichiers, mettre à jour des métadonnées, déplacer des éléments, envoyer à la corbeille, mettre en file d’attente des transformations ou créer des accès partagés.
• Zone grise : lorsque vous n’avez pas reçu de réponse, ne supposez ni le succès ni l’échec ; enregistrez la tentative et confirmez par une consultation.

Quelles opérations de fichiers doivent être protégées

Dans Apification Cloud, l’intégration par API REST serveur à serveur permet de gérer les ressources Cloud, les utilisateurs, la configuration et les tâches de transformation depuis le backend d’un produit intégrateur. Cloud est décrit comme un espace organisé et versionné pour gérer des fichiers, des services et des projets numériques prêts à être partagés. Certaines opérations sont naturellement consultatives ; d’autres changent l’état du workspace où vivent les fichiers, services et projets numériques.

Les transformations exigent également de la prudence. Apification permet de traiter des documents, images, vidéos, fichiers audio et données au moyen d’un assistant guidé, et son intégration permet de gérer les tâches de transformation depuis le backend. Créer ou envoyer une tâche de transformation est une écriture asynchrone : votre application peut perdre la réponse et ne pas savoir si la tâche a été enregistrée. Si vous répétez sans état local ni identité logique stable, vous pouvez finir par payer le coût opérationnel de deux processus équivalents ou mélanger les résultats de versions différentes du fichier.

• Protégez toute action qui change l’état comme candidate à une répétition contrôlée.
• Ne répétez pas des transformations coûteuses sans vérifier s’il existe déjà une tâche associée à la tentative logique.
• Considérez le déplacement d’un élément comme un changement d’organisation, et non d’identité : dans Cloud, ses propriétés et règles d’accès restent associées au même élément.

Modèle recommandé : identité externe, état local et confirmation

Le modèle le plus fiable commence dans votre propre application. Avant d’appeler Apification, créez un enregistrement local d’opération avec un identifiant externe stable du système source, le type d’action, la version logique du contenu et un état initial. Cet enregistrement ne remplace pas l’API ; il sert à ce que votre backend se souvienne de ce qu’il a tenté de faire, avec quel payload et ce qu’il s’attend à trouver ensuite. Dans les intégrations multi-tenant, cette table évite que deux clients, projets ou versions partagent accidentellement la même déduplication.

Après un appel incertain, ne décidez pas uniquement à partir du code d’erreur du client HTTP. Si l’opération était une lecture, vous pouvez la répéter normalement. Si c’était une écriture, consultez d’abord ce que vous pouvez : détail de l’élément, état de la tâche, historique des versions ou enregistrements locaux précédents. Apification Cloud permet de consulter l’historique des éléments, de télécharger des versions antérieures et de restaurer du contenu ; cela aide à reconstruire quel contenu est finalement devenu actif lorsqu’il y a eu une course entre reprises, mises à jour ou déplacements.

• États minimaux : en attente, envoyé, accepté, confirmé, échoué, nécessite une revue.
• Champs minimaux : tenant, objet source, version logique, action, payload normalisé, clé d’opération locale, ressource Cloud résultante et horodatage local.
• Règle pratique : ne supprimez pas l’enregistrement local lorsque le réseau échoue ; c’est précisément la preuve dont vous aurez besoin pour décider de l’étape suivante.

Concevoir une clé idempotente qui ne dépend pas du nom

Même si HTTP définit ce que signifie le fait qu’une requête soit idempotente, chaque API concrète doit être consultée dans son propre contrat. Dans Apification, la page d’intégration indique que le document OpenAPI téléchargeable contient les schémas de requête et de réponse ; utilisez-le pour valider la façon dont chaque appel est construit et les données qu’il renvoie. De plus, conservez dans votre base de données une clé d’opération locale afin de reconnaître quand deux reprises appartiennent à la même tentative logique.

La clé ne doit pas être simplement le nom du fichier ni un timestamp généré à chaque tentative. Le nom change, se répète entre utilisateurs et contient généralement des décisions de présentation, pas une identité métier. Une bonne conception combine tenant, identifiant de l’objet source, type d’action et version logique. Par exemple, une clé conceptuelle pourrait être dérivée de « tenant A + contrat 583 + transformer en PDF optimisé + version 7 ». Si l’utilisateur téléverse une nouvelle version, la clé doit changer ; si la même tentative est seulement répétée à cause d’un timeout, elle doit être conservée.

• Incluez : tenant ou compte source, ressource métier, action exacte, version logique et, le cas échéant, opération de transformation.
• Évitez : timestamps par tentative, UUID aléatoire par reprise, noms visibles de fichier comme seule identité et clés partagées entre actions distinctes.
• Vérifiez : même clé locale, même payload, même intention fonctionnelle et contrat OpenAPI consulté avant d’automatiser les reprises.

Flux pas à pas pour transformer et publier un fichier

Un flux de transformation robuste commence avant l’envoi de la requête. Validez d’abord dans votre système quel fichier métier va être traité et quelle version logique il représente. Ensuite, enregistrez ou gérez le fichier dans Cloud en utilisant l’API correspondante selon le contrat OpenAPI. Enregistrez la référence renvoyée avec votre opération locale. Si la réponse se perd, marquez la tentative comme incertaine et cherchez une confirmation avant d’envoyer une autre copie.

Pour transformer, consultez le contrat de l’opération lorsque vous en avez besoin, préparez une demande compatible avec les schémas documentés et créez la tâche de transformation via l’intégration serveur à serveur. Lorsque vous recevez une acceptation ou une référence de tâche, enregistrez-la ; puis consultez l’API selon le contrat pour vérifier son avancement et ses résultats. Ce n’est que lorsque le résultat est confirmé que vous devriez publier le téléchargement ou générer l’étape de partage appropriée.

• Préparer : résoudre le tenant, l’objet source, la version et le dossier de destination.
• Envoyer : utiliser une clé locale stable pour l’écriture et enregistrer le payload normalisé.
• Confirmer : consulter la tâche jusqu’à obtenir un état et des résultats, sans créer une autre tâche par impatience.
• Publier : partager l’élément ou le téléchargement transformé uniquement après avoir associé le bon résultat à la bonne version.

Quand relancer, consulter ou arrêter le flux

Relancez automatiquement lorsque l’opération est une lecture ou lorsque la requête est idempotente au sens de la RFC 9110. Si l’écriture dépend de règles spécifiques de l’API, ne supposez pas de garanties non documentées : consultez l’OpenAPI, conservez le même payload pour la même tentative logique et enregistrez ce que le client a décidé et pourquoi. La sécurité de la reprise naît de la combinaison entre sémantique HTTP, contrat de l’API et état local.

Consultez avant de répéter lorsque l’erreur s’est produite après l’envoi des octets, lorsque le timeout est arrivé tard ou lorsque votre client ne sait pas si la connexion s’est coupée avant ou après qu’Apification ait reçu la requête. Arrêtez le flux pour une revue humaine lorsque vous détectez un payload différent avec la même intention, plus d’une ressource candidate, des versions mélangées ou des résultats incompatibles avec l’état local. Dans ces cas, répéter peut augmenter les dégâts : il vaut mieux présenter un panneau interne avec l’opération, le tenant, les ressources Cloud possibles, la tâche de transformation et l’action recommandée.

• Relancer : GET d’état et opérations conçues comme idempotentes.
• Consulter : timeout postérieur à l’envoi, réponse perdue, tâche sans référence locale mais acceptation distante possible.
• Arrêter : clés incohérentes, doublons visibles, version source modifiée, transformation déjà terminée pour une autre version.

Erreurs fréquentes et comment Apification s’intègre

Les échecs les plus courants ne sont pas sophistiqués : utiliser des timestamps comme noms uniques, générer une nouvelle clé à chaque reprise, mélanger le fichier original avec une version ultérieure, répéter des transformations asynchrones parce que l’utilisateur a actualisé l’écran, ou considérer qu’un webhook reçu confirme une écriture précédente. Un webhook est un événement postérieur qui doit être traité avec sa propre déduplication ; il ne remplace pas la confirmation de l’appel sortant effectué par votre backend. Séparez les deux circuits : client API vers Apification d’un côté, récepteur de webhooks de l’autre.

Apification s’intègre à cette conception parce qu’il offre une intégration par API REST serveur à serveur, un document OpenAPI avec schémas de requête et de réponse, un Cloud organisé et versionné, la transformation guidée de fichiers, le partage via liens, utilisateurs ou groupes, et des webhooks signés avec reprises, historique et statistiques. La recommandation pratique est de générer le client depuis le contrat OpenAPI ou de le valider contre celui-ci, d’enregistrer les états intermédiaires dans votre base de données et d’utiliser les consultations de Cloud et de transformation pour confirmer les résultats avant d’avancer.

• Ne confondez pas la réception d’événements avec la confirmation des écritures initiées par votre backend.
• N’utilisez pas le nom visible du fichier comme identifiant fonctionnel.
• Ne publiez pas un téléchargement transformé avant de savoir quelle version logique a produit le résultat.
• Ne promettez pas au produit « sans doublons » uniquement parce que vous avez des reprises ; concevez des états, des clés, des consultations et une revue.

Questions fréquentes