PUT VS PATCH: DIFERENCIAS Y CUÁNDO USAR CADA MÉTODO

En el desarrollo de APIs RESTful, uno de los errores más comunes es confundir los verbos HTTP PUT y PATCH. Aunque ambos se utilizan para actualizar recursos, su comportamiento y casos de uso son completamente diferentes.

¿Qué es PUT?

PUT se utiliza para reemplazar un recurso completo. Cuando se realizar una petición PUT, se está enviando la representación total del recurso al servidor. Si algún campo no se incluye en la petición, se eliminará o se establecerá en su valor predeterminado, dependiendo de la implementación.

Características principales

  • Realiza la misma petición varias veces produce el mismo resultado.
  • Reemplaza todo el recurso.
  • Se debe enviar el objeto completo.

Ejemplo

{
  "id": 1,
  "nombre": "John Doe",
  "email": "john.doe@example.com",
  "telefono": "7777-7777",
  "ciudad": "New York",
  "pais": "USA"
}
Aunque solo se quieras cambiar el teléfono, con PUT se debe enviar todo el objeto.

¿Qué es PATCH?

PATCH se utiliza para actualizar parcialmente un recurso. Solo se envían los campos que se desean modificar, dejando el resto intacto.

Características principales

  • No es necesariamente idempotente, depende de la implementación.
  • Solo actualiza lo que se envía.
  • Más eficiente en términos de ancho de banda y seguridad.

Ejemplo

{
  "telefono": "8888-8888"
}
Con una sola línea actualizas únicamente el campo que se necesita.

PUT vs PATCH

Aspecto PUT PATCH
Tipo de actualización Completa (reemplazo) Parcial
Campos requeridos Todos los campos del recurso Solo los que se van a modificar
Idempotencia Sí No siempre
Uso recomendado Reemplazar un recurso entero Actualizaciones específicas
Tamaño de la petición Mayor Menor

¿Cuándo usar cada uno?

  • Usar PUT cuando se quiera reemplazar completamente un recurso o cuando la operación deba ser idempotente.
  • Usar PATCH cuando solo se necesite actualizar uno o varios campos específicos, lo más común en aplicaciones modernas.
Elegir el verbo HTTP correcto mejora la claridad del API, evita errores inesperados, reduce el tráfico de red y hace que el backend sea más predecible y mantenible.