Vous avez créé un endpoint qui accepte un fichier. Un utilisateur télécharge une photo de profil vers POST /avatars, ou votre application envoie un PDF signé vers POST /documents. La route fonctionne dans votre tête. Maintenant, vous devez prouver qu'elle fonctionne via HTTP : choisissez un vrai fichier, attachez-le à un champ de formulaire, envoyez la requête et vérifiez la réponse.
C'est là que de nombreux outils d'API deviennent compliqués. Les téléchargements de fichiers utilisent multipart/form-data, et non du JSON, vous ne pouvez donc pas simplement coller un corps de requête et l'envoyer. Vous avez besoin d'un constructeur de requêtes qui comprend les champs de fichier, et d'un exécuteur de tests qui peut trouver le fichier lorsque le test s'exécute plus tard. Apidog gère les deux, et ce guide vous accompagne sur tout le chemin : envoyer un seul fichier, envoyer un fichier avec du JSON, vérifier la réponse, puis la partie honnête dont personne ne vous prévient, à savoir ce qui se passe lorsque cette même étape de téléchargement s'exécute en mode headless dans le Runner ou la CLI et ne peut pas trouver le fichier. Si vous souhaitez d'abord des informations sur le format lui-même, l'amorce sur le téléchargement de fichiers dans les API explique comment les requêtes multipart sont structurées. La référence MDN sur FormData est un bon complément pour le côté navigateur.
bouton
Qu'est-ce que multipart/form-data et pourquoi les téléchargements en ont besoin
Le corps d'une requête API peut prendre plusieurs formes. Dans la section Body (Corps) d'Apidog, vous pouvez choisir form-data, x-www-form-urlencoded, JSON, XML, raw ou binary. La plupart du temps, vous utilisez JSON. Les téléchargements de fichiers sont l'exception.
Le type de corps form-data correspond à l'en-tête Content-Type: multipart/form-data. C'est le format conçu pour télécharger des fichiers avec d'autres données. Au lieu d'un seul bloc, le corps est divisé en plusieurs parties, chacune avec son propre nom et son propre contenu. Une partie peut être une chaîne de caractères simple comme une légende, une autre partie peut être les octets bruts d'une image. C'est pourquoi un téléchargement de photo et ses métadonnées peuvent voyager dans la même requête.
Le proche parent est x-www-form-urlencoded. Il ressemble à l'éditeur, des paires clé-valeur envoyées dans le corps, mais il est destiné aux formulaires simples sans fichiers. Si votre endpoint accepte un fichier, form-data est celui que vous voulez. N'utilisez x-www-form-urlencoded que lorsque chaque champ est un scalaire court et qu'aucun octet n'est impliqué.
Dans form-data, Apidog affiche chaque paramètre comme une paire clé-valeur, et chaque paramètre a un type : string (chaîne), integer (entier), file (fichier), etc. Ce type par paramètre est toute l'astuce. Définissez un champ sur file et Apidog traitera sa valeur comme un fichier à attacher plutôt que comme du texte à envoyer.
Envoyer un téléchargement de fichier unique et vérifier la réponse
Supposons que vous testiez POST /avatars. Il prend un champ, avatar, contenant une image, et renvoie du JSON avec l'URL stockée. Voici le déroulement.
1. Ouvrez la section Corps et choisissez form-data. Dans votre endpoint ou une nouvelle requête, définissez la méthode sur POST et l'URL sur votre route d'avatars. Ouvrez l'onglet Corps et sélectionnez le type de corps form-data. Apidog définit Content-Type: multipart/form-data pour vous.
2. Ajoutez le paramètre de fichier et définissez son type sur fichier. Ajoutez un paramètre avec la clé avatar. À côté de la clé, utilisez le sélecteur de type pour changer son type de string à file. La cellule de valeur se transforme en un sélecteur de fichiers au lieu d'une zone de texte.
3. Cliquez sur Télécharger et choisissez un fichier local. Cliquez sur Télécharger (Upload) sur la ligne avatar et sélectionnez une image sur votre machine, par exemple jane-profile.png. Apidog enregistre le chemin d'accès à ce fichier.
4. Envoyez la requête. Cliquez sur Envoyer. Apidog lit le fichier à partir du chemin local enregistré, construit le corps multipart, et l'envoie. Bon à savoir d'emblée : Apidog envoie le fichier dans la requête mais ne le stocke pas dans le cloud. Il enregistre uniquement le chemin local, et non les octets. Ce détail sera important plus tard, gardez-le en tête.
{
"id": "usr_8842",
"avatarUrl": "https://cdn.example.com/avatars/usr_8842.png",
"sizeBytes": 48210,
"contentType": "image/png"
}
5. Vérifiez la réponse. Un envoi qui renvoie 200 n'est pas un test réussi en soi. Ajoutez des assertions pour que la vérification soit réelle. Dans Apidog, vous les ajoutez comme assertions post-requête sur l'endpoint ou l'étape du scénario. En termes simples, vous voulez confirmer le statut et que le corps contient une URL utilisable :
status code == 200
$.avatarUrl exists
$.contentType == "image/png"
Ces éléments correspondent directement à l'interface utilisateur d'assertion d'Apidog : une assertion sur le code de statut, une sur la présence de $.avatarUrl via JSONPath, une sur $.contentType. Si vous débutez avec les assertions, le guide sur les assertions d'API présente l'ensemble complet des opérateurs et comment JSONPath cible un champ.
Pour une vérification rapide en dehors de l'outil, le même téléchargement avec curl ressemble à ceci :
curl -X POST https://api.example.com/avatars \
-F "avatar=@jane-profile.png"
Le drapeau -F est la façon de curl de construire une partie multipart, et @ lui indique de lire le contenu du fichier. Le paramètre de fichier form-data d'Apidog fait la même chose avec un sélecteur au lieu d'un drapeau.
Envoyer un fichier et du JSON ensemble
Les endpoints réels acceptent rarement un simple fichier. POST /documents pourrait vouloir le fichier plus des métadonnées : un titre, une catégorie, peut-être un tableau de tags. Vous avez deux façons propres de faire cela dans une seule requête multipart.
Le cas simple est celui des champs scalaires. Ajoutez d'autres paramètres form-data à côté de votre champ de fichier et laissez-les en tant que string ou integer. Une chaîne title, une chaîne category, un file défini sur le type file. Les trois voyagent dans la même requête.
Lorsque les métadonnées sont structurées, comme un objet imbriqué ou un tableau, vous les envoyez sous forme de JSON à l'intérieur d'une partie de chaîne. Ajoutez un paramètre form-data nommé metadata, conservez son type comme string, et collez le JSON directement dans la valeur :
{
"title": "Q3 Invoice",
"category": "billing",
"tags": ["invoice", "2026", "paid"]
}
La requête a donc deux parties : file (type file) transportant q3-invoice.pdf, et metadata (type string) transportant ce JSON. Le serveur lit le fichier d'une partie et analyse le JSON de l'autre. De nombreuses API publiques acceptent les téléchargements de cette manière exacte ; la documentation sur le téléchargement de fichiers de Stripe est un bon exemple d'un endpoint multipart réel qui associe une partie fichier à des champs simples. Ce modèle est suffisamment courant pour que les utilisateurs de Postman le rencontrent également ; si vous migrez, le guide sur le téléchargement d'un fichier et de données JSON dans Postman se transpose parfaitement aux champs form-data d'Apidog.
Besoin d'attacher plus d'un fichier ? Ajoutez un autre paramètre de type file. Un POST /documents qui accepte un fichier principal et une miniature reçoit deux lignes de fichiers, file et thumbnail, chacune avec son propre bouton Télécharger. Il n'y a pas de mode multifichier spécial ; il suffit d'ajouter des paramètres de type fichier jusqu'à ce que vous ayez couvert chaque partie attendue par le endpoint.
Transformer la requête en scénario de test reproductible
Un seul envoi prouve que l'endpoint fonctionne une fois. Pour détecter les régressions, vous voulez que le téléchargement fasse partie d'un scénario de test enregistré qui s'exécute à la demande ou selon un calendrier. Enchaînez les étapes : téléchargez l'avatar, capturez l'id renvoyé, puis appelez GET /users/{id} et vérifiez que l'URL de l'avatar a persisté.
Construisez-le de la même manière que vous avez construit la requête unique, puis enregistrez-le comme une étape dans un scénario. Le guide comment écrire un scénario de test avec Apidog couvre l'enchaînement des étapes et le passage de valeurs entre les étapes. Une fois que le téléchargement fait partie d'un scénario, vous pouvez l'exécuter sur l'environnement de staging à chaque déploiement, ajouter des branches conditionnelles avec la logique conditionnelle dans les scénarios de test d'API, ou le planifier avec les tests d'API planifiés.
Tout ce qui précède fonctionne parfaitement sur votre machine, car votre machine possède le fichier. Cette hypothèse est exactement ce qui va ensuite poser problème.
Le piège : les téléchargements qui s'exécutent ailleurs
Voici la partie que le chemin idéal masque. Apidog stocke le chemin du fichier, et non le fichier lui-même. Sur votre ordinateur portable, c'est invisible, car le chemin résout toujours un fichier réel. Dès que la même étape s'exécute sur une machine différente, le chemin ne pointe plus vers rien.
Vous rencontrerez cela à deux endroits.
Collaboration d'équipe. Lorsqu'un coéquipier ouvre votre requête POST /avatars, il voit le paramètre de fichier et le chemin que vous avez choisi, par exemple /Users/jane/pics/jane-profile.png. Il peut voir la requête, mais il ne peut pas l'envoyer, car ce fichier se trouve sur votre disque, pas sur le sien. Le chemin est local à la machine qui l'a choisi.
Exécutions Runner et CLI. C'est celle qui pose problème en automatisation. Votre scénario de téléchargement passe localement, vous le planifiez dans le Runner ou le lancez depuis la CLI, et l'étape de téléchargement de fichier échoue. Il n'y a rien de mal avec vos assertions. Le runner ne peut tout simplement pas trouver de fichier au chemin enregistré par votre ordinateur portable, car ce chemin n'existe pas sur l'hôte du runner.
La solution découle de la cause. Le fichier doit exister sur la machine qui effectue l'envoi, et le chemin de l'étape doit pointer vers celui-ci.
Pour le Runner : le Runner lit les fichiers depuis un répertoire hôte monté dans son volume. Vous définissez ce montage lors du déploiement du Runner, en utilisant le drapeau -v. Copiez votre fichier à télécharger dans ce répertoire hôte monté. Ensuite, ouvrez les détails de l'étape de téléchargement de fichier dans le scénario, cliquez sur le bouton Édition par lots (Batch Edit) dans le coin supérieur droit, et remplacez la valeur du champ de fichier par le chemin d'accès à l'intérieur du répertoire du Runner, par exemple :
/opt/runner/jane-profile.png
Pour la CLI : même principe. Placez le fichier sur la machine CLI, puis utilisez Édition par lots (Batch Edit) sur l'étape pour pointer le chemin vers son emplacement là-bas, par exemple :
/opt/apidog/runner/jane-profile.png
Plus propre que le codage en dur : utilisez une variable. Au lieu de fixer un chemin littéral dans l'étape, remplacez la valeur par une variable et définissez la valeur de la variable sur le chemin réel du fichier par environnement. Ainsi, le même scénario s'exécute sur votre ordinateur portable, le Runner et le CI sans modifier l'étape à chaque fois. Vous pointez la variable vers /Users/jane/pics/jane-profile.png localement et /opt/runner/jane-profile.png sur le runner, et l'étape elle-même ne change jamais.
Une condition préalable mérite d'être clairement énoncée : le Runner n'accède aux fichiers hôtes qui se trouvent sous le répertoire que vous avez monté avec -v au moment du déploiement. Si votre fichier ne se trouve pas sous ce montage, aucun chemin ne le trouvera. Il s'agit d'un détail de configuration de déploiement, et non d'une limitation du plan. La documentation Apidog sur les requêtes de téléchargement de fichiers détaille les étapes de montage et d'édition en masse si vous souhaitez la version canonique.
Automatiser le workflow avec la CLI Apidog
Une fois votre scénario de téléchargement enregistré, vous pouvez l'exécuter en mode headless dans le CI. Installez la CLI et authentifiez-vous :
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Ensuite, exécutez le scénario enregistré par ID, en le ciblant vers un environnement :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Ici, -t est l'ID du scénario de test, -e est l'ID de l'environnement, et -r est le rapporteur (utilisez cli, html, ou junit, séparés par des virgules pour plusieurs). La CLI exécute vos scénarios enregistrés depuis le projet cloud et signale les succès/échecs avec des codes de sortie, ce qui lui permet de contrôler un pipeline. Les détails de configuration se trouvent dans le guide d'installation de la CLI Apidog.
Une mise en garde honnête, et c'est la même que dans la section précédente : un scénario avec une étape de téléchargement de fichier nécessite que le fichier soit présent sur la machine CLI, et le chemin de l'étape doit pointer vers celui-ci. Placez le fichier sur le runner, puis utilisez Édition par lots (Batch Edit) pour le chemin (ou utilisez une variable) avant l'exécution. Si vous ignorez cela, l'étape de téléchargement ne trouvera pas le fichier même si le reste du scénario est correct. Pour une configuration CI plus complète, y compris le passage d'entrées par ligne, consultez les tests basés sur les données avec la CLI Apidog.
FAQ
Pourquoi mon coéquipier ne peut-il pas envoyer ma requête de téléchargement de fichier ? Apidog stocke le chemin du fichier local, et non le fichier lui-même, et ne télécharge jamais le fichier vers le cloud. Votre coéquipier voit la requête et le chemin que vous avez choisi, mais ce chemin pointe vers un fichier sur votre disque, pas sur le sien. Demandez-lui de placer une copie du fichier sur sa machine et de faire pointer le champ vers son propre chemin. Le même mécanisme explique pourquoi les tests planifiés et les tâches du Runner nécessitent que le fichier soit mis en scène là où ils s'exécutent.
Comment envoyer du JSON avec un fichier dans la même requête ? Gardez le type de corps comme form-data. Ajoutez votre champ de fichier avec le type file, puis ajoutez un autre paramètre avec le type string et collez le JSON dans sa valeur. Le serveur reçoit les deux parties dans une seule requête multipart : le fichier dans une partie, la chaîne JSON dans une autre. C'est la manière standard d'attacher des métadonnées à un téléchargement.
Quel chemin dois-je utiliser pour un fichier dans le Runner ? Utilisez un chemin à l'intérieur du répertoire hôte que vous avez monté dans le volume du Runner avec le drapeau -v au moment du déploiement, par exemple /opt/runner/votre_fichier.jpg. Copiez le fichier dans ce répertoire monté, puis ouvrez l'étape, cliquez sur Édition par lots (Batch Edit), et définissez la valeur du champ sur ce chemin. L'équivalent CLI est /opt/apidog/runner/votre_fichier.jpg.
Y a-t-il une limite de taille de fichier ou une liste de types de fichiers autorisés ? Le comportement de téléchargement dans Apidog concerne la façon dont la requête est construite et d'où le fichier est lu. Vos limites réelles de taille et de type proviennent de l'API que vous testez, alors vérifiez les propres règles de validation de votre serveur et écrivez des assertions contre les réponses qu'il renvoie pour les fichiers trop volumineux ou rejetés.
Dois-je utiliser form-data ou x-www-form-urlencoded pour les téléchargements ? Utilisez form-data. Il correspond à multipart/form-data et est conçu pour transporter des fichiers. x-www-form-urlencoded est destiné aux formulaires simples de champs scalaires courts sans fichier, il ne transportera donc pas votre image ou PDF.
En résumé
Les tests de téléchargement de fichiers se résument à deux choses : construire correctement la requête multipart, et s'assurer que le fichier est accessible partout où le test s'exécute. Dans Apidog, vous définissez le Corps sur form-data, changez le type de votre champ en file, cliquez sur Télécharger (Upload), ajoutez tout JSON comme partie chaîne, puis envoyez et vérifiez. Lorsque vous déplacez le même scénario vers le Runner ou la CLI, préparez le fichier sur cette machine et redirigez le chemin avec Édition par lots (Batch Edit) ou une variable, et l'exécution automatisée se comportera comme votre exécution locale.
Vous voulez l'essayer sur votre propre endpoint ? Téléchargez Apidog, dirigez une requête form-data vers votre route de téléchargement, et observez la réponse. C'est gratuit pour commencer, aucune carte de crédit n'est requise.