POST
Uso
Una solicitud POST envía una entidad al recurso especificado. El servidor determina cómo tratar la representación adjunta según la semántica propia del recurso. A diferencia de PUT, que apunta al URI de un recurso concreto, POST delega el procesamiento al recurso identificado por el URI de destino.
La cabecera Content-Type indica el formato del cuerpo de la solicitud. En los formularios HTML y las API son habituales tres codificaciones.
application/x-www-form-urlencoded
La codificación predeterminada de los formularios HTML. Los datos se estructuran como pares clave-valor separados por ampersands (&), con las claves y los valores unidos por signos de igual (=). Los caracteres no alfanuméricos se representan con codificación porcentual.
name=Alice&role=adminmultipart/form-data
Cada campo ocupa una parte independiente delimitada por una cadena de frontera declarada en la cabecera Content-Type. Esta codificación admite datos binarios, como la subida de archivos. La cabecera Content-Disposition de cada parte da nombre al campo.
text/plain
Sin estructura prescrita. El servidor procesa el cuerpo en bruto según su propia lógica.
Las solicitudes POST repetidas no son idempotentes. Enviar el mismo formulario dos veces crea dos recursos o desencadena el procesamiento dos veces, a diferencia de PUT, donde una solicitud repetida produce el mismo estado en el servidor.
Las respuestas a POST solo se pueden almacenar en caché cuando la respuesta incluye información explícita de frescura y una cabecera Content-Location coincidente.
Envío de formulario
Un cliente envía datos de formulario en formato codificado para URL. El servidor crea un trabajo y responde con 201 Created.
Solicitud
POST /jobs HTTP/1.1
Host: api.example.re
Content-Type: application/x-www-form-urlencoded
Content-Length: 17
name=backup&pri=2Respuesta
HTTP/1.1 201 Created
Location: /jobs/47
Content-Type: application/json
Content-Length: 38
{"id":47,"name":"backup","priority":2}Subida de archivo multipart
Un cliente sube un archivo usando codificación multipart. La cadena de frontera ----Boundary separa cada parte. El servidor acepta la subida y devuelve 202 Accepted.
Solicitud
POST /uploads HTTP/1.1
Host: api.example.re
Content-Type: multipart/form-data; boundary=----Boundary
Content-Length: 196
------Boundary
Content-Disposition: form-data; name="title"
Q4 Report
------Boundary
Content-Disposition: form-data; name="file"; filename="report.pdf"
Content-Type: application/pdf
<binary data>
------Boundary--Respuesta
HTTP/1.1 202 Accepted
Location: /uploads/91
Content-Length: 0JSON API
Un cliente envía una carga útil JSON para crear un usuario nuevo. El servidor devuelve el recurso creado con un campo id.
Solicitud
POST /users HTTP/1.1
Host: api.example.re
Content-Type: application/json
Content-Length: 41
{"email":"alice@example.re","role":"ops"}Respuesta
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 50
{"id":112,"email":"alice@example.re","role":"ops"}CORS
POST es un método incluido en la lista segura de CORS, pero solo cuando el Content-Type es application/x-www-form-urlencoded, multipart/form-data o text/plain. Un POST con application/json o cualquier otro tipo de contenido activa una solicitud de verificación previa OPTIONS.
POST frente a GET
POST transporta los datos en el cuerpo de la solicitud en lugar de en la URL. Así los parámetros no quedan en el historial del navegador, los registros del servidor ni las cabeceras Referer, lo que hace que POST se adapte mejor a los datos sensibles.
Las respuestas a POST no se almacenan en caché de forma predeterminada ni pueden guardarse como marcadores. POST no es seguro ni idempotente, por lo que los envíos repetidos crean recursos duplicados o desencadenan el procesamiento varias veces.
POST no tiene un límite práctico de tamaño de cuerpo, mientras que GET está limitado por restricciones de longitud de URL en torno a los 2048 caracteres.
Las cookies con SameSite=Lax bloquean las solicitudes POST entre sitios, pero permiten los GET entre sitios. Esto otorga a POST un cierto grado de protección integrada contra CSRF que GET no tiene.
Seguridad
Los datos de POST no aparecen en las URL, el historial del navegador ni las cabeceras Referer. Esto reduce el riesgo de exposición accidental de datos en comparación con GET.
POST sigue siendo vulnerable a los ataques CSRF si no se usan tokens adecuados. Los formularios de páginas maliciosas envían solicitudes POST a otros orígenes de forma automática. Las cookies con SameSite=Lax ofrecen protección parcial al bloquear la transmisión de cookies en POST entre sitios, pero los tokens CSRF dedicados siguen siendo necesarios.
Un POST sobre HTTP simple transmite los datos en texto claro. Se requiere HTTPS para proteger el cuerpo de la solicitud en tránsito.
POST frente a PATCH
POST crea recursos nuevos en URI elegidos por el servidor. PATCH modifica recursos existentes en URI conocidos.
POST delega la semántica de procesamiento por completo en el servidor. PATCH cuenta con formatos de parche definidos, como JSON Patch y JSON Merge Patch, que describen las modificaciones concretas que se deben aplicar.
Cuando un cliente necesita actualizar campos concretos de un recurso existente, PATCH es el método apropiado. POST sirve para crear recursos nuevos o desencadenar procesamiento en el servidor.