PATCH

Uso

Una solicitud PATCH envía un conjunto de instrucciones que describen cómo modificar un recurso existente. A diferencia de PUT, que reemplaza el recurso completo, PATCH cambia únicamente los campos o propiedades indicados.

El cuerpo de la solicitud contiene un documento de parche en un formato que el servidor entiende. La cabecera Content-Type identifica el formato del parche. La cabecera Accept-Patch en las respuestas del servidor anuncia los formatos de parche admitidos.

Nota

PATCH no está obsoleto. El método se estandarizó en 2010 y sigue siendo una parte activa de la semántica de HTTP. La confusión surge porque PATCH se añadió más tarde que otros métodos y algunos frameworks antiguos carecen de soporte nativo.

Nota

PATCH no ofrece garantías de idempotencia. Aplicar el mismo parche dos veces puede producir resultados distintos (por ejemplo, añadir dos veces un elemento a una lista). Los parches concurrentes sobre el mismo recurso corren el riesgo de entrar en conflicto si no se usan solicitudes condicionales (If-Unmodified-Since o If-Match).

Formatos de parche habituales

JSON Patch expresa las modificaciones como un array ordenado de operaciones: add, remove, replace, move, copy y test.

Content-Type: application/json-patch+json

[
  {"op":"replace","path":"/email",
   "value":"alice@example.re"},
  {"op":"add","path":"/verified","value":true}
]

JSON Merge Patch adopta un enfoque más sencillo. El documento de parche refleja la estructura del recurso de destino. Los campos presentes en el parche sobrescriben los valores existentes. Establecer un campo en null elimina ese campo.

Content-Type: application/merge-patch+json

{"email":"alice@example.re","nickname":null}

Atomicidad

El servidor aplica todos los cambios de un documento de parche como una única operación atómica. Si alguna instrucción falla, se rechaza el parche completo y el recurso permanece sin cambios.

Nota

Una solicitud PATCH tiene efectos secundarios y no se garantiza que sea idempotente. Dos parches idénticos aplicados en secuencia a una operación de “añadir a una lista” producen un resultado distinto al de una única aplicación.

JSON Merge Patch

Un cliente actualiza la dirección de correo electrónico del usuario 42 usando el formato JSON Merge Patch. El servidor aplica el cambio y devuelve 200 OK con el recurso actualizado.

Solicitud

PATCH /users/42 HTTP/1.1
Host: api.example.re
Content-Type: application/merge-patch+json
Content-Length: 28

{"email":"alice@example.re"}

Respuesta

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 51

{"id":42,"name":"Alice","email":"alice@example.re"}

JSON Patch

Un cliente aplica dos operaciones a un recurso de configuración: reemplazar el indicador debug y añadir un nuevo campo de nivel de registro. El servidor lo confirma con 204 No Content.

Solicitud

PATCH /config/app HTTP/1.1
Host: api.example.re
Content-Type: application/json-patch+json
Content-Length: 102

[
  {"op":"replace","path":"/debug","value":false},
  {"op":"add","path":"/logLevel","value":"warn"}
]

Respuesta

HTTP/1.1 204 No Content

Parche condicional

Una solicitud condicional que usa If-Unmodified-Since evita modificar un recurso que ya ha sido cambiado por otro cliente. Si el recurso se modificó después de la marca de tiempo indicada, el servidor devuelve 412 Precondition Failed.

Solicitud

PATCH /docs/report.json HTTP/1.1
Host: api.example.re
Content-Type: application/merge-patch+json
If-Unmodified-Since: Mon, 01 Jan 2024 12:00:00 GMT
Content-Length: 21

{"status":"reviewed"}

Respuesta

HTTP/1.1 412 Precondition Failed
Content-Length: 0

CORS

Las solicitudes PATCH de origen cruzado siempre desencadenan una comprobación previa (preflight) de CORS. El navegador envía primero una solicitud OPTIONS para confirmar que el servidor permite PATCH sobre el recurso de destino.

PATCH frente a PUT

PATCH envía solo los cambios, lo que hace que las solicitudes sean más pequeñas y más eficientes en ancho de banda para recursos grandes. PUT envía la representación completa cada vez, independientemente de cuántos campos hayan cambiado.

PUT es idempotente. Enviar dos veces la misma solicitud PUT produce el mismo estado en el servidor. No se garantiza que PATCH sea idempotente, porque operaciones como añadir un elemento a una lista producen resultados distintos en cada aplicación.

Use PATCH cuando actualice campos concretos de un recurso existente. Use PUT cuando reemplace el recurso completo por una nueva representación.

PATCH frente a POST

PATCH modifica un recurso existente en un URI conocido. POST crea nuevos recursos o desencadena procesamiento del lado del servidor.

PATCH utiliza semánticas de parche definidas, como JSON Patch y JSON Merge Patch. POST delega la semántica por completo en el servidor y no prescribe ningún formato para el cuerpo de la solicitud.