Método PATCH

Definición

PATCH es un método HTTP que aplica modificaciones parciales a un recurso. A diferencia de PUT (que reemplaza el recurso completo), PATCH actualiza solo los campos especificados en el cuerpo de la petición. Esto hace que PATCH sea más eficiente para actualizar recursos grandes cuando solo necesitas cambiar unos pocos campos.

PATCH puede ser idempotente (recomendado) o no idempotente dependiendo de la implementación. El cuerpo de la petición describe los cambios a aplicar, no el estado completo del recurso. Los formatos comunes incluyen JSON Patch (RFC 6902), JSON Merge Patch (RFC 7396), o actualizaciones simples de campos.

PATCH es esencial para APIs modernas donde importa la eficiencia de ancho de banda, especialmente para aplicaciones móviles o APIs con representaciones de recursos grandes. Permite a los clientes modificar atributos específicos sin conocer o enviar la estructura completa del recurso.

Ejemplo

Perfil de Usuario - Actualizar Solo Email:

PATCH /api/users/123 HTTP/1.1
Content-Type: application/json

{
  "email": "[email protected]"
}

Publicación de Blog - Cambiar Estado:

PATCH /api/posts/456 HTTP/1.1
Content-Type: application/json

{
  "status": "published",
  "publishedAt": "2026-01-09T10:00:00Z"
}

Producto - Actualizar Precio y Stock:

PATCH /api/products/SKU-789 HTTP/1.1
Content-Type: application/json

{
  "price": 149.99,
  "stock": 25
}

JSON Patch - Operaciones Estructuradas:

PATCH /api/users/123 HTTP/1.1
Content-Type: application/json-patch+json

[
  { "op": "replace", "path": "/email", "value": "[email protected]" },
  { "op": "add", "path": "/phone", "value": "+1-555-0123" },
  { "op": "remove", "path": "/tempField" }
]

Analogía

Editar un Google Doc: PATCH es como hacer pequeñas ediciones en un documento: cambias un error tipográfico aquí, añades una frase allá, sin reescribir todo el documento. No creas una versión completamente nueva (eso es PUT), solo modificas las partes específicas que necesitan actualización.

Ajustar Configuración del Coche: Piensa en ajustar los espejos laterales de tu coche. No reemplazas el coche entero (PUT), solo ajustas la posición del espejo. PATCH es hacer pequeños ajustes a componentes existentes.

Edición de Fotos: PATCH es como usar la herramienta de corrección puntual en Photoshop: arreglas una imperfección específica sin rehacer toda la imagen. Estás haciendo correcciones dirigidas, no empezando de cero.

Ejemplo de Código

// PATCH - Actualización simple de campos (JSON Merge Patch)
PATCH /api/users/789 HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "department": "Product",
  "role": "manager"
}

// Respuesta - 200 OK
HTTP/1.1 200 OK
Content-Type: application/json
ETag: "8f9e7d6c5b4a3f2e1d0c9b8a7f6e5d4c"

{
  "id": 789,
  "firstName": "Bob",
  "lastName": "Smith",
  "email": "[email protected]",
  "role": "manager",
  "department": "Product",
  "manager": 456,
  "hireDate": "2024-01-15",
  "active": true,
  "updatedAt": "2026-01-09T11:00:00Z"
}

// PATCH - Formato JSON Patch (RFC 6902)
PATCH /api/users/789 HTTP/1.1
Content-Type: application/json-patch+json

[
  {
    "op": "replace",
    "path": "/email",
    "value": "[email protected]"
  },
  {
    "op": "add",
    "path": "/skills",
    "value": ["javascript", "python", "go"]
  },
  {
    "op": "test",
    "path": "/version",
    "value": 3
  }
]

// Respuesta - 200 OK
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 789,
  "email": "[email protected]",
  "skills": ["javascript", "python", "go"],
  "version": 4
}

// PATCH - Caso de error (validación de campo)
PATCH /api/users/789 HTTP/1.1
Content-Type: application/json

{
  "email": "invalid-email"
}

// Respuesta - 400 Bad Request
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "validation_error",
  "message": "Invalid email format",
  "field": "email"
}

// PATCH - Actualización condicional con ETag
PATCH /api/users/789 HTTP/1.1
If-Match: "8f9e7d6c5b4a3f2e1d0c9b8a7f6e5d4c"
Content-Type: application/json

{
  "active": false
}

// Respuesta - 412 Precondition Failed (recurso cambiado)
HTTP/1.1 412 Precondition Failed
Content-Type: application/json

{
  "error": "precondition_failed",
  "message": "Resource has been modified",
  "currentETag": "new-etag-value"
}

Diagrama

sequenceDiagram
    participant Client
    participant Server
    participant Database

    Client->>Server: PATCH /api/users/123
    Note over Client,Server: Solo campos modificados

    Server->>Database: Obtener recurso actual
    Database-->>Server: Estado actual

    Server->>Server: Aplicar cambios parciales
    Note over Server: Fusionar/validar campos

    Server->>Database: Actualizar solo campos modificados
    Database-->>Server: Actualizado exitosamente

    Server-->>Client: 200 OK
    Note over Server,Client: Devolver recurso actualizado

    Client->>Server: PATCH con cabecera If-Match
    Note over Client,Server: Bloqueo optimista

    Server->>Database: Verificar ETag/versión
    Database-->>Server: ETag no coincide

    Server-->>Client: 412 Precondition Failed
    Note over Server,Client: Prevenir actualizaciones perdidas

Notas de Seguridad

SECURITY NOTES

CRÍTICO - …

Configuración y Validación:

Validar todos los campos antes de aplicar cambios.
Nunca confiar en nombres de campo proporcionados por el cliente: usar listas blancas para prevenir vulnerabilidades de asignación masiva.
Implementar autorización apropiada para asegurar que los usuarios solo pueden hacer PATCH a recursos que poseen.
Usar ETags o números de versión para prevenir problemas de actualización perdida.
Sanitizar valores de entrada para prevenir ataques de inyección.

Monitoreo y Protección:

Considerar limitación de tasa para endpoints PATCH para prevenir abuso.
Registrar todas las operaciones PATCH para pistas de auditoría.
Validar que las actualizaciones parciales mantienen la consistencia de datos (por ejemplo, formato de email, relaciones requeridas).
Ser cauteloso con operaciones “test” de JSON Patch que pueden filtrar el estado del recurso.
Implementar idempotencia cuando sea posible para manejar peticiones PATCH duplicadas de forma segura.

Mejores Prácticas

Usar para actualizaciones parciales: PATCH debe modificar solo los campos especificados
Soportar JSON Merge Patch: Actualizaciones simples de campos (RFC 7396)
Considerar JSON Patch: Para operaciones complejas (RFC 6902)
Hacerlo idempotente: El mismo PATCH debe producir el mismo resultado
Devolver recurso completo: La respuesta debe incluir el recurso actualizado completo
Validar datos parciales: Asegurar que los campos modificados mantienen la consistencia
Usar ETags: Implementar bloqueo optimista con cabecera If-Match
Documentar campos permitidos: Especificar claramente qué campos se pueden modificar con PATCH
Manejar null cuidadosamente: Definir semánticas (eliminar campo vs. establecer a null)
Devolver 200 OK: Con recurso actualizado, o 204 No Content si no hay cuerpo

Errores Comunes

Permitir a los clientes hacer PATCH a cualquier campo sin validación (vulnerabilidad de asignación masiva). No implementar idempotencia, causando problemas en reintentos. Confundir PATCH con PUT: enviar recurso completo en lugar de solo cambios. No validar que las actualizaciones parciales mantienen la integridad de datos. Olvidar manejar actualizaciones concurrentes con ETags. Permitir PATCH de campos de solo lectura o calculados. No documentar qué campos son modificables con PATCH. Usar PATCH para operaciones que realmente no son actualizaciones (usar POST en su lugar). Tratar PATCH como no idempotente cuando debería serlo. No devolver el recurso actualizado completo en la respuesta.