Qu'est-ce que multipart/form-data Content-Type ? Uploads, Exemples

Qu'est-ce que multipart/form-data ?

multipart/form-data est un Content-Type de requête HTTP utilisé pour soumettre des données de form contenant des fichiers ou contenu binaire en plus de champs texte. Contrairement à application/x-www-form-urlencoded (l'encoding form par défaut pour les champs texte uniquement), multipart/form-data envoie chaque champ de form comme une "partie" séparée dans le body de la requête, avec ses propres headers et contenu. Cette structure est essentielle pour les uploads de fichiers — les bytes binaires du fichier ne peuvent pas être URL-encodés en toute sécurité comme paire key=value.

Le format est défini dans RFC 7578. Les navigateurs l'utilisent automatiquement quand un form HTML a enctype="multipart/form-data" et contient un élément <input type="file">.

Comment multipart/form-data fonctionne

Le header Content-Type inclut un boundary — un string généré aléatoirement qui sépare chaque partie dans le body de la requête :

POST /api/upload HTTP/1.1
Host: api.example.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Length: 554

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="username"

alice
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="avatar"; filename="photo.jpg"
Content-Type: image/jpeg

[bytes JPEG binaires ici]
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Chaque partie est précédée par -- + le string boundary. Chaque partie a son propre header Content-Disposition et Content-Type optionnel.

multipart/form-data vs application/x-www-form-urlencoded

Quand utiliser multipart/form-data

• Uploads de fichiers. Le use case original.
• Forms texte + fichier mixtes.
• Plusieurs fichiers dans une requête.
• Submission de form avec texte non-ASCII.

Envoyer multipart/form-data depuis du code

JavaScript (navigateur fetch + FormData)

const fd = new FormData();
fd.append('username', 'alice');
fd.append('avatar', fileInput.files[0]);

fetch('/api/upload', {
  method: 'POST',
  body: fd  // Le navigateur définit Content-Type avec boundary automatiquement
});

Important : ne définissez PAS Content-Type manuellement en envoyant FormData — le navigateur doit ajouter la boundary lui-même.

curl

curl -X POST https://api.example.com/upload \
  -F "username=alice" \
  -F "avatar=@/path/to/photo.jpg"

Python (requests)

import requests
files = {'avatar': open('photo.jpg', 'rb')}
data = {'username': 'alice'}
requests.post('https://api.example.com/upload', files=files, data=data)

Parsing côté serveur

• Express + Multer.
• Django. request.FILES['avatar']
• Flask. request.files['avatar']
• FastAPI. def upload(file: UploadFile)
• Spring Boot. @RequestParam MultipartFile
• Rails. params[:avatar]

Limites d'upload multipart et pièges

• Limites body size serveur. NGINX défaut 1 MB ; AWS API Gateway 10 MB ; Cloudflare 100 MB Pro.
• Pression mémoire sur uploads. Utilisez parsers streaming.
• Collisions de boundary. Théoriquement possibles, extrêmement rares.
• CSRF sur uploads. Les endpoints d'upload ont besoin de la même protection CSRF.
• Validation de file-type. Ne faites pas confiance au Content-Type du client. Validez basé sur le contenu réel du fichier (magic bytes).

Considérations de performance

• Évitez d'envoyer de gros fichiers à travers votre serveur API. Utilisez URLs signed S3/Cloud Storage pour upload direct.
• Uploads chunked / resumable. Pour très gros fichiers protocoles comme tus.io ou AWS S3 multipart upload.
• HTTP/2. Aide avec uploads multi-fichiers.

Erreurs courantes

• 413 Payload Too Large.
• 400 Bad Request — boundary manquante.
• 500 — exception du parser multipart.
• Fichier vide reçu. Le client a utilisé FormData mais a défini Content-Type manuellement.

Tester les uploads multipart at scale

• Varier les tailles de fichier.
• Utiliser du contenu de fichier réel.
• Tester les cas boundary.
• Multi-région.
• Uploads concurrents.

FAQ : multipart/form-data

Pourquoi la boundary est-elle dans le header Content-Type ?

Le serveur a besoin de connaître la boundary pour parser le body. Il ne peut pas la dériver du body lui-même.

Puis-je utiliser multipart/form-data sans fichiers ?

Oui. Ça fonctionne pour les champs texte uniquement aussi. Mais pour les forms texte uniquement, application/x-www-form-urlencoded ou JSON est plus efficace.

Quelle est la différence entre multipart/form-data et multipart/mixed ?

Les deux sont multipart, mais multipart/form-data est spécifique pour les soumissions de form HTML. multipart/mixed est plus générique.

Comment envoyer JSON + un fichier ensemble ?

Deux patterns : (1) une partie est text/JSON, l'autre est le fichier ; (2) embarquer le fichier comme base64 dans JSON (~33% overhead).

Pourquoi mon upload échoue-t-il quand je définis Content-Type manuellement ?

Parce que vous n'avez pas inclus la boundary. Laissez votre client HTTP définir le header automatiquement.

Quelle est la taille max de fichier pour uploads multipart ?

Dépend de la config serveur. NGINX défaut 1 MB. AWS API Gateway cap dur 10 MB. Pour fichiers plus gros URLs S3 signed ou uploads chunked (tus.io).

Tester les endpoints upload multipart avec LoadFocus

Si vous load-testez des APIs upload de fichiers, LoadFocus exécute des scripts JMeter et k6 qui peuvent envoyer des payloads multipart réalistes depuis 25+ régions cloud avec jusqu'à 12 500 VUs. Inscrivez-vous sur loadfocus.com/signup — pas de carte de crédit — et lancez votre premier test upload multipart en moins de 5 minutes.