Qu'est-ce qu'un payload dans une API ? JSON, XML, exemples

Qu'est-ce qu'un payload dans une API ?

Le payload (charge utile) d'une API est la partie d'une requête ou d'une réponse qui transporte les données dans le corps, par opposition à l'URL, à la méthode, aux en-têtes et au code de statut qui la décrivent. Dans un POST qui crée un utilisateur, le payload est le JSON de cet utilisateur ; dans la réponse d'un GET, c'est la ressource demandée. C'est la partie que le code de votre application lit, valide et enregistre.

Le terme vient des réseaux, où il désignait la cargaison d'un paquet par opposition à ses en-têtes de routage. Les en-têtes indiquent au serveur comment lire le message ; le payload est le message.

Où se trouve le payload dans un message HTTP

Un message HTTP se compose d'une ligne de départ, d'en-têtes, d'une ligne vide puis du corps. Le payload se trouve dans le corps.

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 73
Authorization: Bearer xyz123

{
  "name": "Alice",
  "email": "alice@example.com",
  "role": "member"
}

Tout ce qui précède la ligne vide relève des métadonnées. L'objet JSON en dessous est le payload. Quelles méthodes en envoient un :

• POST, PUT et PATCH envoient normalement un payload dans la requête, car leur rôle est de transmettre des données au serveur.
• GET, HEAD et DELETE n'ont normalement pas de corps. Les paramètres passent dans le chemin ou dans la query string (l'article How are Parameters Sent in an HTTP POST Request? montre la différence, en anglais).
• Les réponses contiennent en général un payload aussi. Les exceptions sont les réponses sans contenu, comme 204 et 304.

Formats de payload courants

• JSON est le standard de la plupart des API REST : lisible et pris en charge par tous les langages. Voir qu'est-ce que JSON.
• XML est plus ancien et plus verbeux, et reste courant pour SOAP et les intégrations d'entreprise.
• application/x-www-form-urlencoded est ce qu'envoient les formulaires HTML simples : name=Alice&role=member.
• multipart/form-data réunit champs de formulaire et fichiers dans une seule requête. Voir multipart/form-data.
• Binaire (application/octet-stream, image/png) transporte des octets bruts, comme les téléchargements et les images.
• Protocol Buffers et MessagePack sont des encodages binaires compacts utilisés par gRPC et les API exigeantes en performances. Ils sont plus petits que JSON, mais illisibles sans décodage.

L'en-tête Content-Type indique de quel format il s'agit. S'il manque ou s'il est faux, le destinataire lit mal le corps.

Taille du payload et limites

• Les serveurs plafonnent le corps des requêtes. nginx, par exemple, fixe client_max_body_size à 1m par défaut et répond 413 si le corps est plus gros. La RFC 9110 appelle désormais ce statut "Content Too Large".
• Les gros payloads coûtent du temps et de la mémoire. Beaucoup de serveurs mettent tout le corps en tampon avant de le traiter ; en forte concurrence, la mémoire utilisée et la latence augmentent.
• Compressez les payloads texte. gzip ou brotli (négociés via Accept-Encoding et Content-Encoding) réduisent souvent beaucoup le JSON, mais le gain dépend des données.
• Ne renvoyez pas tout d'un coup. Livrez les grandes collections page par page. Voir pagination d'API.

Validez chaque payload reçu

• Vérifiez la structure avec un schéma (JSON Schema, Zod, Pydantic) et rejetez ce qui ne correspond pas.
• Imposez une taille maximale pour qu'une seule requête énorme n'épuise pas la mémoire.
• Contrôlez les types et les plages, et n'acceptez que les champs attendus. Sinon, un client peut glisser "role": "admin" (mass assignment).
• Prenez l'identité de l'appelant dans l'authentification, jamais dans un identifiant du payload.

Erreurs courantes

• Content-Type absent ou incorrect. Envoyez Content-Type: application/json avec les corps JSON.
• Conflits de jeu de caractères. Utilisez UTF-8 de bout en bout, sinon les accents et les emojis arrivent déformés.
• JSON dans une chaîne JSON. Le JSON intégré sous forme de texte s'échappe une fois, pas deux.
• Journaliser des payloads entiers. Mots de passe, jetons et données personnelles finissent dans vos logs. Filtrez d'abord les champs sensibles.
• Envoyer un corps avec GET. HTTP ne lui donne aucune signification définie ; serveurs et proxys peuvent l'ignorer ou le refuser.

Les payloads en test de charge et en supervision

Un test qui envoie {"k":"v"} ne mesure presque rien. L'analyse, la validation et les écritures en base croissent avec la taille et la forme du payload ; utilisez donc des corps proches de la production et variez-les par utilisateur virtuel (voir data-driven load testing scripts, en anglais). Testez aussi juste en dessous et juste au-dessus de la limite de taille, et attendez-vous à un 413 propre plutôt qu'à un 500. Dans les tests d'API, vérifiez le corps de la réponse, pas seulement le code de statut.

LoadFocus exécute vos scripts JMeter et k6 depuis 25 régions cloud (tests de charge), et les étapes de transformer cURL, HAR, Postman ou OpenAPI en test de charge (en anglais) permettent de partir d'une commande cURL. Pour des contrôles continus, la surveillance d'API peut vérifier le code de statut, le corps de la réponse, les en-têtes et le temps de réponse. Pour envoyer un payload ponctuel depuis le navigateur, utilisez l'outil gratuit curl online ; les options sont détaillées dans la commande curl.

Questions fréquentes sur les payloads d'API

L'URL fait-elle partie du payload ?

Non. Le chemin et la query string sont des métadonnées qui identifient la ressource. Le payload, c'est le corps.

Les requêtes GET ont-elles un payload ?

En pratique non. HTTP ne définit aucune signification pour le corps d'un GET et beaucoup de serveurs et de proxys l'ignorent. Pour GET, utilisez des paramètres de chemin ou de query.

Quelle différence entre payload et corps ?

Ce sont presque des synonymes. Corps est le terme HTTP pour les octets qui suivent les en-têtes ; payload est le terme courant pour les données utiles qu'il contient.

Une réponse peut-elle ne pas avoir de payload ?

Oui. Les réponses 204 No Content et 304 Not Modified n'ont pas de corps, et un DELETE renvoie souvent 204.

Quelle est la taille maximale d'un payload ?

Elle est fixée par le serveur, le proxy ou la passerelle placés devant votre API, pas par HTTP. nginx utilise 1m par défaut. Vérifiez la limite à chaque niveau et adaptez-la à votre cas.

Comment tester les payloads d'API sous charge ?

Utilisez un outil capable de paramétrer les corps par utilisateur virtuel, comme JMeter ou k6, et envoyez des tailles et des formes réalistes plutôt que des valeurs minimales.