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.
Essayez Apidog dès aujourd’hui
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.
Ce guide couvre le workflow complet :
- envoyer un fichier unique ;
- envoyer un fichier avec des métadonnées JSON ;
- vérifier la réponse ;
- exécuter le scénario dans le Runner ou la CLI sans erreur de chemin.
Pour comprendre le format en détail, consultez l'amorce sur le téléchargement de fichiers dans les API. La référence MDN sur FormData complète utilement le sujet côté navigateur.
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 d'Apidog, vous pouvez choisir form-data, x-www-form-urlencoded, JSON, XML, raw ou binary. Dans la plupart des cas, vous utiliserez 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
Ce format permet d'envoyer un fichier avec d'autres données dans une même requête. Le corps est découpé en plusieurs parties :
- une partie peut contenir une chaîne, comme un titre ;
- une partie peut contenir un entier ;
- une partie peut contenir les octets bruts d'une image ou d'un PDF.
C'est ainsi qu'une photo et ses métadonnées peuvent être envoyées ensemble.
Le format proche, x-www-form-urlencoded, utilise aussi des paires clé-valeur, mais il est prévu pour des formulaires simples sans fichiers. Si votre endpoint accepte un fichier, utilisez form-data.
Dans form-data, Apidog affiche chaque paramètre comme une paire clé-valeur et permet de définir son type : string, integer, file, etc. Définissez un champ sur file pour qu'Apidog attache le fichier au lieu d'envoyer son chemin comme une simple chaîne.
Envoyer un fichier unique et vérifier la réponse
Supposons que vous testiez POST /avatars. L'endpoint attend un champ avatar contenant une image et renvoie du JSON avec l'URL du fichier stocké.
1. Choisissez form-data
Dans votre endpoint ou dans une nouvelle requête :
- définissez la méthode sur
POST; - renseignez l'URL de votre route, par exemple
/avatars; - ouvrez l'onglet Body ;
- sélectionnez
form-data.
Apidog configure alors Content-Type: multipart/form-data.
2. Ajoutez le champ de fichier
Ajoutez un paramètre avec la clé :
avatar
Dans le sélecteur de type, remplacez string par file. La zone de valeur devient alors un sélecteur de fichiers.
3. Sélectionnez le fichier local
Cliquez sur Télécharger (Upload) sur la ligne avatar, puis choisissez un fichier local, par exemple :
jane-profile.png
Apidog enregistre le chemin local du fichier.
4. Envoyez la requête
Cliquez sur Envoyer. Apidog lit le fichier depuis le chemin enregistré, construit le corps multipart et l'envoie à l'API.
Point important : Apidog envoie le fichier dans la requête, mais ne stocke pas ses octets dans le cloud. Seul le chemin local est enregistré. Cette distinction est essentielle pour les exécutions Runner et CLI.
Exemple de réponse :
{
"id": "usr_8842",
"avatarUrl": "https://cdn.example.com/avatars/usr_8842.png",
"sizeBytes": 48210,
"contentType": "image/png"
}
5. Ajoutez des assertions
Un statut 200 seul ne suffit pas à valider le comportement. Vérifiez au minimum le statut, l'URL retournée et le type de contenu.
Ajoutez des assertions post-requête comme :
status code == 200
$.avatarUrl exists
$.contentType == "image/png"
Dans Apidog, cela correspond à :
- une assertion sur le code de statut ;
- une assertion JSONPath vérifiant l'existence de
$.avatarUrl; - une assertion sur la valeur de
$.contentType.
Pour aller plus loin, consultez le guide sur les assertions d'API.
Pour tester rapidement le même endpoint depuis un terminal :
curl -X POST https://api.example.com/avatars \
-F "avatar=@jane-profile.png"
L'option -F indique à curl de construire une requête multipart. Le préfixe @ demande à curl de lire le contenu du fichier local.
Envoyer un fichier et du JSON ensemble
Les endpoints réels acceptent rarement un fichier seul. Un endpoint POST /documents peut attendre :
- un PDF ;
- un titre ;
- une catégorie ;
- des tags ;
- d'autres métadonnées.
Cas simple : champs scalaires
Ajoutez plusieurs paramètres form-data :
| Clé | Type | Exemple |
|---|---|---|
file |
file |
q3-invoice.pdf |
title |
string |
Q3 Invoice |
category |
string |
billing |
Tous les champs seront envoyés dans la même requête multipart.
Cas structuré : JSON dans une partie texte
Pour un objet imbriqué ou un tableau, ajoutez un paramètre form-data nommé metadata, gardez son type sur string, puis collez le JSON dans la valeur :
{
"title": "Q3 Invoice",
"category": "billing",
"tags": ["invoice", "2026", "paid"]
}
Votre requête contient alors deux parties principales :
-
file, de typefile, pourq3-invoice.pdf; -
metadata, de typestring, pour les métadonnées JSON.
Le serveur lit le fichier depuis une partie, puis analyse le JSON depuis l'autre. Ce modèle est courant dans les API publiques. La documentation Stripe sur le téléchargement de fichiers montre un exemple concret d'endpoint multipart associant un fichier à des champs simples.
Si vous migrez depuis Postman, consultez aussi ce guide sur le téléchargement d'un fichier et de données JSON dans Postman.
Attacher plusieurs fichiers
Pour envoyer plusieurs fichiers, ajoutez simplement plusieurs paramètres de type file.
Par exemple, pour POST /documents :
| Clé | Type |
|---|---|
file |
file |
thumbnail |
file |
Chaque ligne possède son propre bouton Télécharger. Il n'existe pas de mode multifichier séparé : ajoutez un champ file pour chaque partie attendue par votre endpoint.
Transformer la requête en scénario de test reproductible
Un envoi manuel valide un cas ponctuel. Pour détecter les régressions, ajoutez le téléchargement à un scénario de test.
Exemple de scénario :
- envoyez
POST /avatarsavec un fichier ; - récupérez l'
idretourné ; - appelez
GET /users/{id}; - vérifiez que l'URL de l'avatar a été persistée.
Construisez d'abord la requête de téléchargement, puis enregistrez-la comme étape dans un scénario. Le guide comment écrire un scénario de test avec Apidog explique comment enchaîner les étapes et réutiliser les valeurs extraites.
Une fois le scénario enregistré, vous pouvez :
- l'exécuter sur l'environnement de staging après chaque déploiement ;
- ajouter des branches avec la logique conditionnelle dans les scénarios de test d'API ;
- le lancer périodiquement via les tests d'API planifiés.
Ce workflow fonctionne localement parce que votre machine possède le fichier. Cette hypothèse devient un problème dès que le scénario s'exécute ailleurs.
Le piège : les téléchargements qui s'exécutent ailleurs
Apidog stocke le chemin du fichier, pas le fichier lui-même.
Sur votre poste, cela passe souvent inaperçu :
/Users/jane/pics/jane-profile.png
Ce chemin existe sur votre ordinateur. Mais si la même requête est ouverte par un collègue, exécutée par un Runner ou lancée depuis une machine CI, ce chemin ne désigne plus forcément un fichier réel.
Collaboration d'équipe
Un collègue peut voir votre champ avatar et le chemin associé, mais il ne peut pas envoyer la requête si le fichier n'existe pas sur son poste.
La solution est simple :
- placez une copie du fichier sur la machine du collègue ;
- mettez à jour le champ de fichier avec un chemin local valide ;
- ou utilisez une variable d'environnement pour éviter de modifier le scénario.
Exécutions Runner et CLI
Le même problème apparaît en automatisation :
- le scénario passe en local ;
- vous le planifiez dans le Runner ou l'exécutez en CI ;
- l'étape d'upload échoue.
Le problème ne vient généralement pas des assertions. Le Runner ou la CLI ne trouve simplement pas le fichier au chemin enregistré sur votre ordinateur.
La règle est la suivante :
Le fichier doit être présent sur la machine qui envoie la requête, et le chemin configuré dans le scénario doit pointer vers ce fichier.
Configurer un fichier pour le Runner
Le Runner lit les fichiers depuis un répertoire hôte monté dans son volume via le drapeau -v.
Procédure :
- montez un répertoire hôte lors du déploiement du Runner ;
- copiez le fichier à envoyer dans ce répertoire ;
- ouvrez l'étape de téléchargement dans le scénario ;
- cliquez sur Édition par lots (Batch Edit) ;
- remplacez la valeur du champ de fichier par le chemin disponible dans le Runner.
Exemple :
/opt/runner/jane-profile.png
Configurer un fichier pour la CLI
Le principe est identique pour la CLI :
- placez le fichier sur la machine qui exécute la CLI ;
- modifiez le chemin du champ de fichier via Édition par lots ;
- utilisez un chemin valide sur cette machine.
Exemple :
/opt/apidog/runner/jane-profile.png
Éviter les chemins codés en dur avec des variables
Au lieu d'écrire un chemin différent dans chaque étape, utilisez une variable.
Par exemple :
{{avatar_file_path}}
Définissez ensuite sa valeur selon l'environnement :
# Local
/Users/jane/pics/jane-profile.png
# Runner
/opt/runner/jane-profile.png
# CI
/opt/apidog/runner/jane-profile.png
Le scénario reste identique, tandis que chaque environnement fournit son propre chemin de fichier.
Le Runner ne peut accéder qu'aux fichiers situés sous le répertoire monté avec -v. Si le fichier n'est pas dans ce montage, aucun chemin ne permettra de le lire.
Pour les étapes détaillées, consultez la documentation Apidog sur les requêtes de téléchargement de fichiers.
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 un pipeline CI.
Installez la CLI et authentifiez-vous :
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Exécutez ensuite un scénario enregistré avec son ID et un environnement :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Options utilisées :
| Option | Description |
|---|---|
-t |
ID du scénario de test |
-e |
ID de l'environnement |
-r |
Reporter : cli, html ou junit
|
Vous pouvez fournir plusieurs reporters séparés par des virgules.
La CLI exécute les scénarios enregistrés dans le projet cloud et remonte les succès ou les échecs avec des codes de sortie exploitables par votre pipeline.
Pour l'installation et la configuration, consultez le guide d'installation de la CLI Apidog.
Attention : le fichier doit toujours être disponible sur la machine CLI. Avant l'exécution :
- copiez le fichier sur le runner CI ;
- pointez le champ vers le bon chemin avec Édition par lots ;
- ou fournissez ce chemin via une variable d'environnement.
Pour une configuration CI plus complète, incluant les 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 local du fichier, et non le fichier lui-même. Votre collègue voit la requête, mais le chemin pointe vers votre disque.
Il doit :
- placer une copie du fichier sur sa machine ;
- mettre à jour le champ avec son propre chemin ;
- ou définir une variable de chemin adaptée à son environnement.
Le même principe s'applique aux tests planifiés et aux tâches Runner.
Comment envoyer du JSON avec un fichier dans la même requête ?
Utilisez form-data :
- ajoutez le fichier avec le type
file; - ajoutez un second paramètre, par exemple
metadata, avec le typestring; - collez le JSON dans la valeur de ce paramètre.
Le serveur recevra le fichier et la chaîne JSON comme deux parties de la même requête multipart.
Quel chemin utiliser pour un fichier dans le Runner ?
Utilisez un chemin situé dans le répertoire monté avec -v lors du déploiement du Runner.
Exemple :
/opt/runner/votre_fichier.jpg
Copiez d'abord le fichier dans ce répertoire, puis définissez ce chemin dans l'étape via Édition par lots.
Pour la CLI, un chemin possible est :
/opt/apidog/runner/votre_fichier.jpg
Y a-t-il une limite de taille ou de type de fichier dans Apidog ?
Apidog construit la requête et lit le fichier depuis le chemin local. Les limites réelles de taille et de format proviennent de l'API testée.
Vérifiez donc les règles de validation de votre serveur et ajoutez des assertions pour les cas suivants :
- fichier trop volumineux ;
- type MIME non autorisé ;
- extension invalide ;
- contenu rejeté par l'API.
Dois-je utiliser form-data ou x-www-form-urlencoded ?
Utilisez form-data pour les fichiers.
form-data correspond à multipart/form-data et permet d'envoyer des octets de fichier. x-www-form-urlencoded convient uniquement aux champs scalaires courts sans fichier.
En résumé
Pour tester un téléchargement de fichier, vous devez :
- choisir
form-data; - définir le champ de fichier sur le type
file; - sélectionner le fichier local ;
- ajouter les métadonnées JSON comme champ
stringsi nécessaire ; - envoyer la requête ;
- ajouter des assertions sur la réponse.
Pour exécuter le même scénario dans le Runner, la CLI ou un pipeline CI :
- placez le fichier sur la machine d'exécution ;
- assurez-vous qu'il est accessible depuis le volume monté pour le Runner ;
- utilisez le bon chemin, idéalement via une variable d'environnement.
Vous voulez l'essayer sur votre endpoint ? Téléchargez Apidog, créez une requête form-data vers votre route d'upload et vérifiez la réponse.
Top comments (0)