En el diseño REST de API, PUT y PATCH son dos métodos HTTP que se usan para actualizar recursos en el servidor. La diferencia entre PUT y PATCH en REST APIs está en cómo realizan esas actualizaciones y en los escenarios en que cada uno resulta más adecuado. Ambos métodos están diseñados para modificar datos existentes, pero entender la diferencia entre PUT y PATCH en REST API ayuda a los desarrolladores a elegir la mejor opción según la naturaleza del cambio que necesitan aplicar. En esta entrada del blog exploramos esa diferencia, el debate PATCH vs. actualización REST, cuándo usar cada método y cómo elegir el más adecuado para distintos casos de uso.
¿Qué es PUT en REST APIs?
Para entender la diferencia entre PUT y PATCH en REST APIs, primero hay que saber qué es PUT. Según Sección 9.6 RFC 2616, el método PUT en las solicitudes REST API indica que la entidad incluida debe almacenarse bajo el Request-URI proporcionado.
Si el Request-URI apunta a un recurso que ya existe, la entidad incluida DEBE considerarse como una versión modificada del recurso que reside en el servidor de origen. Si el Request-URI no apunta a un recurso existente y ese URI puede ser definido como un nuevo recurso por el agente de usuario solicitante, el servidor de origen puede crear el recurso con ese URI.
En otras palabras, el método PUT se utiliza para actualizar un recurso completo en el servidor. Esto convierte a PUT en una actualización más «completa», que se usa habitualmente cuando es necesario reemplazar el recurso por entero.
Por tanto, PUT es la mejor opción para los siguientes casos de uso:
- Actualizar un recurso completo (por ejemplo, actualizar un perfil de usuario con información totalmente nueva).
- Reemplazar un elemento o registro completo.
- Cuando la identidad del recurso es clara y sus datos deben actualizarse por completo.
En sistemas como Elasticsearch, las operaciones idempotentes son necesarias para garantizar la consistencia de los datos. Por ejemplo, actualizar un documento en Elasticsearch mediante PUT garantiza que la misma solicitud pueda repetirse sin efectos secundarios no deseados.
¿Qué es PATCH en REST APIs?
Ahora que hemos visto PUT en REST APIs, veamos qué es PATCH en REST APIs y cómo funciona antes de comparar PUT y PATCH en REST APIs. Según lo definido en RFC 5789, el método PATCH en REST API solicita que el conjunto de cambios descrito en la entidad de la solicitud se aplique al recurso identificado por el Request-URI.
Esto se alinea con la distinción entre PUT y PATCH en REST API: solo se envían los datos que deben modificarse, y el servidor aplica esos cambios al recurso existente sin alterar el resto. Los desarrolladores suelen crear parches para representar estos cambios incrementales, lo que garantiza una transferencia de datos mínima y actualizaciones eficientes.
Por eso el método PATCH en REST API es más adecuado para los siguientes casos de uso:
- Actualizar solo un subconjunto de campos de un recurso (por ejemplo, cambiar la dirección de correo electrónico o el número de teléfono de un usuario). Un ejemplo de PATCH API podría implicar enviar únicamente el nuevo correo electrónico, dejando los demás campos sin cambios.
- Mejorar el rendimiento reduciendo el volumen de datos enviados.
- Cuando se quiere actualizar un recurso de forma incremental en lugar de reemplazarlo por completo.
- Crear parches para encapsular cambios en campos concretos, como modificar el correo electrónico de un usuario, sin afectar a datos no relacionados.
Para plataformas como CMS headless que gestionan estructuras de contenido complejas, usar PATCH para actualizaciones menores, como modificar un único campo, puede reducir la carga del servidor y mejorar el rendimiento.
Con estos dos métodos explicados, ya tienes una idea clara de qué son PUT y PATCH en REST APIs. Antes de entrar en las diferencias entre PUT y PATCH en REST APIs, sin embargo, necesitamos hablar sobre la idempotencia en ambos métodos.
Idempotencia en PUT vs. PATCH en REST APIs
En REST APIs, la idempotencia es la propiedad de una operación que, al ejecutarse varias veces con los mismos datos de entrada, produce siempre el mismo resultado. Esto significa que repetir la misma solicitud debe tener el mismo efecto en el servidor, independientemente de cuántas veces se ejecute. Es un factor clave para garantizar la estabilidad y la previsibilidad en una API. Pero ¿qué relación tiene con la diferencia entre PUT y PATCH en REST API?
El método PUT y la idempotencia
El método PUT en REST API es siempre idempotente, porque está diseñado para reemplazar el recurso completo en una URI concreta con los datos enviados en la solicitud. En otras palabras, si realizas varias solicitudes PUT con los mismos datos, el resultado será siempre el mismo.
¿Por qué es idempotente PUT? Al hacer una solicitud PUT, le estás diciendo al servidor: "Este es el estado completo y exacto que quiero para este recurso." Tanto si envías la solicitud una vez como muchas veces, el recurso resultante será siempre idéntico.
Por ejemplo, imagina que actualizas la dirección de correo electrónico de un usuario. Si realizas la misma solicitud PUT varias veces, el resultado no cambiará, porque el recurso se reemplaza con los mismos datos en cada ocasión.
Ejemplo:
| PUT /users/1{"username": "john_doe","email": "[email protected]"} |
Si envías esta solicitud varias veces, el resultado siempre será el mismo:
| {"username": "john_doe","email": "[email protected]"} |
Aunque los datos del usuario ya sean estos, volver a enviar la solicitud no cambia nada. Reemplaza los datos con los mismos datos, por lo que el efecto es idéntico sin importar cuántas veces se repita. Eso es precisamente lo que hace a PUT idempotente.
El método PATCH y la idempotencia
El método PATCH en REST API, por su parte, también es idempotente en general, pero con mayor flexibilidad. Al crear parches, asegúrate de que las operaciones sean idempotentes (por ejemplo, asignar un valor concreto) para evitar efectos secundarios no deseados al repetir solicitudes. Si PATCH es idempotente o no depende de la operación y de los datos que se modifican.
¿Por qué es idempotente PATCH? En las solicitudes PATCH, la idempotencia implica que aplicar el mismo parche varias veces produce el mismo resultado. Esto se cumple siempre que el parche no genere efectos secundarios adicionales al aplicarse repetidamente. Si sigues aplicando el mismo parche con los mismos datos, el resultado no debería cambiar tras la primera aplicación.
Por ejemplo, si solo actualizas el correo electrónico de un usuario, enviar la misma solicitud PATCH varias veces no modificará el resultado después de la primera vez, aunque se repita en múltiples ocasiones. El correo del usuario seguirá siendo el mismo y el estado del recurso no cambiará.
Ejemplo de PATCH en API:
| PATCH /users/1{"email": "[email protected]"} |
Si el correo ya era [email protected], volver a aplicar este PATCH no producirá ningún cambio, lo que lo hace idempotente.
Sin embargo, PATCH también puede ser no idempotente en ciertos casos. Por ejemplo, si una operación PATCH modifica un contador o añade elementos a una lista (como incrementar un número o añadir un elemento a un array), aplicar el mismo PATCH repetidamente puede dar lugar a resultados distintos. Esto vulneraría la propiedad de idempotencia.
Ejemplo de PATCH API REST no idempotente:
| PATCH /counter/1{"increment": 1} |
Si aplicas este PATCH repetidamente, el contador seguirá incrementándose y el valor será distinto cada vez. No es idempotente porque el resultado cambia con cada aplicación.
Ahora que conoces los conceptos fundamentales, podemos ver algunos escenarios de ejemplo para entender mejor la diferencia entre PUT y PATCH en REST APIs.
Casos de ejemplo: PUT vs. PATCH en REST APIs
Dejando la teoría a un lado, veamos la diferencia entre PUT y PATCH con ejemplos que incluyen tanto operaciones idempotentes como no idempotentes.
Escenario 1: solicitud PUT - reemplazar un recurso completo
Imagina un endpoint API para gestionar productos en un sistema de comercio electrónico. Necesitas actualizar todos los detalles de un producto: su nombre, precio y descripción. Este es un ejemplo típico del método HTTP PUT frente a PATCH, donde PUT se usa para reemplazar el recurso completo del producto.
Producto inicial:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
Quieres actualizar el precio y la descripción de un producto. Envías una solicitud PUT con el recurso completo:
Solicitud PUT:
| PUT /products/1001{"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Si realizas esta solicitud PUT una o varias veces, el resultado siempre será el mismo. Los datos del producto se actualizarán con el nuevo precio y la nueva descripción, y el resultado será idéntico en cada llamada. Esto garantiza el carácter idempotente de PUT.
Resultado (tras la solicitud PUT):
| {"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Escenario 2: Solicitud PATCH – Actualización parcial de un recurso
Ahora considera una solicitud PATCH para actualizar solo parte de los datos del producto, por ejemplo la descripción. PATCH API ejemplo: si quieres cambiar la descripción del producto sin modificar su precio, PATCH es la opción correcta. Para implementarlo, crearías parches que contengan únicamente los campos que necesitan modificación, como la descripción en este API REST ejemplo de PATCH.
Producto inicial:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
Solicitud PATCH:
| PATCH /products/1001{"description": "A lightweight, powerful laptop."} |
Al enviar esta solicitud PATCH, solo se actualizará el campo de descripción. Si envías la misma solicitud PATCH varias veces, la descripción no cambiará tras la primera actualización, lo que hace que la solicitud sea idempotente.
Resultado (tras la solicitud PATCH):
| {"id": 1001,"name": "Laptop","price": 999.99,"description": "A lightweight, powerful laptop."} |
Si aplicas el mismo PATCH de nuevo, la descripción del producto seguirá siendo la misma que quedó tras el primer PATCH. El resultado es consistente, lo que hace que PATCH sea idempotente en este escenario.
Escenario 3: Solicitud PATCH – Operación no idempotente
Veamos una operación PATCH no idempotente. Supón que existe un endpoint para el saldo de la cartera de un usuario y quieres incrementar ese saldo. Aquí se puede ilustrar una diferencia clave entre PUT y PATCH: PATCH sumará un valor al saldo cada vez que se ejecute.
Cartera inicial:
| GET /users/1/wallet{"id": 1,"balance": 100.00} |
Solicitud PATCH:
| PATCH /users/1/wallet{"increment": 50.00} |
Esta solicitud PATCH incrementará el saldo de la cartera en 50 $. Si la envías varias veces, el saldo seguirá aumentando con cada PATCH, produciendo un resultado distinto en cada llamada. Es no idempotente porque aplicar el mismo PATCH repetidamente genera un resultado diferente.
Resultado (tras la primera solicitud PATCH):
| {"id": 1,"balance": 150.00} |
Resultado (tras la segunda solicitud PATCH):
| {"id": 1,"balance": 200.00} |
En este caso, PATCH no es idempotente porque solicitudes repetidas con los mismos datos producen resultados distintos.
Resumen: Diferencias clave entre PUT y PATCH en REST APIs
La diferencia clave entre PUT y PATCH en REST API está en cómo gestionan las actualizaciones. PUT reemplaza el recurso completo, por lo que cualquier campo omitido se elimina, lo que puede provocar pérdida de datos. Por eso los desarrolladores usan PATCH para actualizaciones parciales: para no sobreescribir campos sin cambios y mantener la integridad de los datos.
Esto hace que PATCH sea más eficiente para actualizaciones parciales. Un ejemplo de PATCH en API: si solo quieres actualizar el correo electrónico de un usuario, basta con enviar ese campo, a diferencia de una solicitud PUT que requeriría enviar todos los datos del usuario.
Con PUT, hay que enviar el payload completo. Todos los campos son obligatorios, y cualquier campo omitido se borrará. PATCH, en cambio, solo envía los campos que deben actualizarse, lo que lo hace más eficiente, especialmente en recursos grandes con cambios mínimos. El método PATCH en REST API permite solicitudes más pequeñas y específicas, reduciendo la transferencia de datos.
Tanto PUT como PATCH son idempotentes. Esto significa que repetir la misma solicitud produce el mismo resultado. Sin embargo, PUT es más predecible porque reemplaza el recurso completo. PATCH, al modificar solo los campos indicados, puede dar resultados distintos según cómo el servidor gestione las actualizaciones.
Por ejemplo, si un PATCH incrementa un contador, repetir la solicitud puede producir resultados diferentes. Aun así, las operaciones PATCH en API pueden diseñarse para ser idempotentes.
En resumen, la diferencia entre PUT y PATCH en REST API se reduce al tipo de actualización: PATCH es para cambios parciales, mientras que PUT reemplaza el recurso completo. Ambos son idempotentes, pero PATCH puede ser más complejo.
Conclusiones
PUT y PATCH son métodos HTTP fundamentales en el diseño de REST API, pero tienen propósitos distintos, y ahí está la esencia de su diferencia. Entender cuándo usar cada uno, con los ejemplos que hemos visto en este artículo, te permitirá mejorar la eficiencia, la claridad y la funcionalidad de tu API. Elegir el método correcto (PATCH vs PUT en REST) según tu caso de uso hará que tu API sea más eficiente, fácil de mantener y amigable para el usuario. Considera siempre el tipo de actualización, si es completa o parcial, junto con el impacto en el rendimiento y la integridad de los datos, y elige el método que mejor se ajuste a tus necesidades.
