¿Qué es un payload en una API? JSON, XML, ejemplos

¿Qué es un payload en una API?

El payload (carga útil) de una API es la parte de una solicitud o respuesta que transporta los datos en el cuerpo, a diferencia de la URL, el método, las cabeceras y el código de estado que la describen. En un POST que crea un usuario, el payload es el JSON de ese usuario; en la respuesta de un GET, es el recurso solicitado. Es la parte que el código de tu aplicación lee, valida y guarda.

El término viene de las redes, donde designaba la carga de un paquete frente a sus cabeceras de enrutamiento. Las cabeceras indican al servidor cómo leer el mensaje; el payload es el mensaje.

Dónde está el payload en un mensaje HTTP

Un mensaje HTTP se compone de una línea inicial, cabeceras, una línea vacía y el cuerpo. El payload va en el cuerpo.

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"
}

Todo lo que está sobre la línea vacía son metadatos. El objeto JSON de debajo es el payload. Qué métodos lo llevan:

• POST, PUT y PATCH suelen enviar un payload en la solicitud, porque su función es enviar datos al servidor.
• GET, HEAD y DELETE normalmente no llevan cuerpo. Los parámetros viajan en la ruta o en la query string (el artículo How are Parameters Sent in an HTTP POST Request? muestra la diferencia, en inglés).
• Las respuestas también suelen llevar payload. Las excepciones son las respuestas sin contenido, como 204 y 304.

Formatos de payload habituales

• JSON es el estándar de la mayoría de las APIs REST: legible y compatible con todos los lenguajes. Consulta qué es JSON.
• XML es más antiguo y más verboso, y sigue siendo habitual en SOAP y en integraciones empresariales.
• application/x-www-form-urlencoded es lo que envían los formularios HTML simples: name=Alice&role=member.
• multipart/form-data une campos de formulario y archivos en una sola solicitud. Consulta multipart/form-data.
• Binario (application/octet-stream, image/png) transporta bytes sin procesar, como descargas e imágenes.
• Protocol Buffers y MessagePack son codificaciones binarias compactas que usan gRPC y las APIs críticas en rendimiento. Pesan menos que JSON, pero no se pueden leer sin decodificar.

La cabecera Content-Type declara de cuál se trata. Si falta o es incorrecta, el receptor interpreta mal el cuerpo.

Tamaño del payload y límites

• Los servidores limitan el cuerpo de las solicitudes. nginx, por ejemplo, fija client_max_body_size en 1m por defecto y responde 413 si el cuerpo es mayor. RFC 9110 llama ahora a ese estado "Content Too Large".
• Los payloads grandes cuestan tiempo y memoria. Muchos servidores almacenan todo el cuerpo en búfer antes de procesarlo, así que con concurrencia suben el uso de memoria y la latencia.
• Comprime los payloads de texto. gzip o brotli (negociados con Accept-Encoding y Content-Encoding) suelen reducir mucho el JSON, aunque el ahorro depende de los datos.
• No devuelvas todo de golpe. Entrega las colecciones grandes por páginas. Consulta paginación de API.

Valida cada payload que recibes

• Comprueba la estructura con un esquema (JSON Schema, Zod, Pydantic) y rechaza lo que no encaje.
• Impón un tamaño máximo para que una sola solicitud enorme no agote la memoria.
• Comprueba tipos y rangos y acepta solo los campos esperados. Si no, un cliente puede colar "role": "admin" (mass assignment).
• Toma la identidad de quien llama de la autenticación, nunca de un ID dentro del payload.

Errores habituales

• Content-Type ausente o incorrecto. Envía Content-Type: application/json con los cuerpos JSON.
• Conflictos de codificación. Usa UTF-8 de extremo a extremo; si no, los acentos y los emojis llegan rotos.
• JSON dentro de una cadena JSON. El JSON incrustado como texto se escapa una vez, no dos.
• Registrar payloads completos. Contraseñas, tokens y datos personales acaban en tus logs. Filtra antes los campos sensibles.
• Enviar cuerpo en un GET. HTTP no le da ningún significado definido, y servidores y proxies pueden ignorarlo o rechazarlo.

Payloads en pruebas de carga y monitorización

Una prueba que envía {"k":"v"} mide muy poco. El análisis, la validación y las escrituras en base de datos crecen con el tamaño y la forma del payload, así que usa cuerpos parecidos a los de producción y varíalos por usuario virtual (consulta data-driven load testing scripts, en inglés). Prueba también justo por debajo y por encima del límite de tamaño, y espera un 413 limpio en lugar de un 500. En las pruebas de API, comprueba el cuerpo de la respuesta, no solo el código de estado.

LoadFocus ejecuta tus scripts de JMeter y k6 desde 25 regiones en la nube (pruebas de carga), y con los pasos de convertir cURL, HAR, Postman u OpenAPI en una prueba de carga (en inglés) puedes empezar desde un comando cURL. Para comprobaciones continuas, la monitorización de API puede validar código de estado, cuerpo de la respuesta, cabeceras y tiempo de respuesta. Para enviar un payload puntual desde el navegador, usa la herramienta gratuita curl online; los flags están en el comando curl.

Preguntas frecuentes sobre payloads de API

¿La URL forma parte del payload?

No. La ruta y la query string son metadatos que identifican el recurso. El payload es el cuerpo.

¿Las solicitudes GET tienen payload?

En la práctica no. HTTP no define ningún significado para el cuerpo de un GET y muchos servidores y proxies lo ignoran. En GET usa parámetros de ruta o de query.

¿Qué diferencia hay entre payload y cuerpo?

Son casi sinónimos. Cuerpo es el término de HTTP para los bytes que siguen a las cabeceras; payload es el término habitual para los datos con significado que contiene.

¿Puede una respuesta no tener payload?

Sí. Las respuestas 204 No Content y 304 Not Modified no tienen cuerpo, y un DELETE suele devolver 204.

¿Cuál es el tamaño máximo de un payload?

Lo fija el servidor, el proxy o el gateway que está delante de tu API, no HTTP. nginx usa 1m por defecto. Revisa el límite en cada capa y ajústalo a tu caso.

¿Cómo pruebo payloads de API bajo carga?

Usa una herramienta que permita parametrizar los cuerpos por usuario virtual, como JMeter o k6, y envía tamaños y formas realistas en lugar de marcadores mínimos.