JSON Patch: La Forma Inteligente de Actualizar los Datos de tu API

Has construido una API moderna. El GET obtiene datos, el POST crea nuevos recursos, hasta ahora todo bien. Pero cuando se trata de actualizar datos, las cosas se complican.

Digamos que un usuario solo quiere cambiar su correo electrónico. ¿Realmente necesitas que reenvíe el perfil de usuario completo? Eso es torpe, ineficiente y propenso a errores, especialmente con conexiones lentas o actualizaciones conflictivas.

Hay una forma mejor: JSON Patch.
En lugar de enviar el objeto completo, envías solo los cambios. Piensa en ello como darle a un sastre una lista de modificaciones en lugar de rehacer todo el traje.

Dado que JSON se ha convertido en el lenguaje universal para las API, JSON Patch ofrece una solución ligera y elegante para actualizaciones parciales.

Por supuesto, diseñar y probar API con JSON Patch requiere las herramientas adecuadas. Ahí es donde entra Apidog. Te permite crear, probar y validar solicitudes JSON Patch con facilidad, para que sepas que tus actualizaciones funcionan según lo previsto antes de escribir una sola línea de código. Lo mejor de todo es que es gratis para descargar y empezar a experimentar hoy mismo.

A continuación, desglacemos qué es JSON Patch, cómo funciona y por qué debería ser parte de tu próximo proyecto.

El problema: la solicitud PUT "ciega"

Para entender por qué JSON Patch es tan útil, primero necesitamos entender el problema que resuelve. Tradicionalmente, la actualización de un recurso en una API RESTful se realiza con el método HTTP PUT.

Una solicitud PUT está destinada a ser idempotente (realizar la misma solicitud varias veces tiene el mismo efecto que hacerla una vez) y normalmente reemplaza el recurso completo en la URL de destino con la nueva representación proporcionada en el cuerpo de la solicitud.

Imaginemos un recurso de perfil de usuario:

GET /users/123

{
  "id": 123,
  "username": "johndoe",
  "email": "john.old@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "age": 30,
  "accountStatus": "active",
  "preferences": {
    "theme": "light",
    "notifications": true
  },
  "signUpDate": "2023-01-15"
}

Ahora, si John solo quiere cambiar su dirección de correo electrónico, una solicitud PUT típica se vería así:

PUT /users/123

{
  "id": 123,
  "username": "johndoe",
  "email": "john.new@example.com", // El campo cambiado
  "firstName": "John",
  "lastName": "Doe",
  "age": 30,
  "accountStatus": "active",
  "preferences": {
    "theme": "light",
    "notifications": true
  },
  "signUpDate": "2023-01-15"
}

¿Ves el problema? Tuvimos que enviar de vuelta cada campo, aunque el 99% de los datos no cambiaron. Este enfoque tiene varias desventajas:

1. Mayor Ancho de Banda: Estamos enviando una gran cantidad de datos innecesarios por la red. Para recursos grandes, esto puede ser un impacto significativo en el rendimiento, especialmente en redes móviles.
2. Mayor Riesgo de Conflictos: Si otro proceso actualiza el campo age mientras John está editando su email, la solicitud PUT de John podría sobrescribir accidentalmente esa nueva edad con el valor antiguo que envió.
3. Complejidad para el Cliente: La aplicación cliente debe primero GET el recurso completo, modificar el campo específico y luego PUT todo de nuevo. Son varios pasos y requiere que el cliente gestione todo el estado.

Aquí es donde el método HTTP PATCH viene al rescate.

La solución: Introducción de HTTP PATCH y JSON Patch

El método HTTP PATCH se introdujo para permitir modificaciones parciales a un recurso. A diferencia de PUT, que reemplaza el recurso completo, PATCH aplica un conjunto de cambios al recurso.

Pero hay un inconveniente: el estándar HTTP no define cuál debe ser el formato de esos "cambios". Podrías inventar el tuyo propio. Podrías enviar algo como:

{ "op": "change_email", "value": "new@example.com" }

Pero esto sería personalizado, no estándar, y otros desarrolladores tendrían que aprender tu lenguaje específico.

Esta es la brecha que JSON Patch llena. JSON Patch (definido en RFC 6902) es un formato estandarizado para especificar cambios que se aplicarán a un documento JSON. Proporciona un lenguaje claro e inequívoco para describir exactamente cómo debe modificarse un documento JSON.

Cuando combinas el método HTTP PATCH con un cuerpo formateado como un documento JSON Patch, tienes una forma potente y basada en estándares para realizar actualizaciones parciales.

Cómo funciona JSON Patch: lo básico

Un documento JSON Patch es siempre un array JSON. Cada elemento del array es un objeto de operación. Estas operaciones se aplican al documento de destino en orden, y todo el parche es atómico, lo que significa que si una sola operación falla, todo el parche se aborta y el documento permanece sin cambios.

Cada objeto de operación tiene un miembro op obligatorio (abreviatura de "operación") que especifica la acción a realizar. Las operaciones más comunes son add, remove, replace, move y copy.

Veamos el ejemplo anterior de John cambiando su correo electrónico. Usando JSON Patch, la solicitud se vuelve dramáticamente más simple:

PATCH /users/123

[
  { "op": "replace", "path": "/email", "value": "john.new@example.com" }
]

¡Eso es todo! Estamos enviando una sola operación: "reemplazar el valor en la ruta '/email' con este nuevo valor". La solicitud es pequeña, clara y orientada a la intención. No tocamos ningún otro campo.

Entendiendo la propiedad path

La propiedad path es un JSON Pointer (RFC 6901), una cadena que utiliza una sintaxis basada en barras para navegar a través del documento JSON hasta el valor específico que deseas manipular.

• "/email" apunta al campo email de nivel raíz.
• "/preferences/theme" apunta al campo theme dentro del objeto preferences.
• "/firstName" apunta al campo firstName.

Esta sintaxis es potente para navegar por estructuras JSON anidadas.

JSON Patch vs. JSON Merge Patch

Los desarrolladores a menudo confunden JSON Patch (RFC 6902) con JSON Merge Patch (RFC 7386). Aclaremos.

JSON Patch:

• Describe una secuencia de operaciones.
• Muy preciso y permite actualizaciones complejas.
• Ejemplo: reemplazar, mover, copiar.

JSON Merge Patch:

• Envía un documento JSON parcial que se fusiona con el original.
• Más simple, pero menos flexible.
• Ejemplo: { "name": "Bob" } reemplazaría el campo de nombre.

En resumen:

• Usa JSON Merge Patch para actualizaciones simples y superficiales.
• Usa JSON Patch para operaciones complejas o múltiples.

Las operaciones de JSON Patch

Desglosemos las operaciones más comunes con ejemplos. Usaremos el mismo perfil de usuario como nuestro documento objetivo.

1. La operación add

La operación add se utiliza para insertar un nuevo valor en un objeto o array.

Añadir una nueva propiedad a un objeto:

{ "op": "add", "path": "/twitterHandle", "value": "@johndoe" }

Esto añade un nuevo campo twitterHandle al objeto de usuario.

Añadir un elemento a un array (en un índice específico):

Imagina que el usuario tiene un array "hobbies": ["reading", "cycling"].

{ "op": "add", "path": "/hobbies/1", "value": "hiking" }

Esto inserta "senderismo" en el índice 1, resultando en ["reading", "hiking", "cycling"]. Para añadir al final del array, puedes usar /-: { "op": "add", "path": "/hobbies/-", "value": "hiking" }.

2. La operación remove

La operación remove elimina un valor en una ubicación especificada.

Eliminar una propiedad de un objeto:

{ "op": "remove", "path": "/age" }

Esto elimina todo el campo age del objeto de usuario.

Eliminar un elemento de un array:

{ "op": "remove", "path": "/hobbies/0" }

Esto elimina el primer elemento (índice 0) del array hobbies.

3. La operación replace

La operación replace es esencialmente una combinación de remove y add en la misma ruta. Reemplaza el valor existente en una ubicación con un nuevo valor. Nuestro ejemplo de correo electrónico fue un replace clásico.

Cambiar la preferencia de tema de un usuario:

{ "op": "replace", "path": "/preferences/theme", "value": "dark" }

4. La operación move

La operación move elimina un valor de una ubicación y lo añade a otra.

Mover un valor de una propiedad a otra:

{ "op": "move", "from": "/firstName", "path": "/first_name" }

Esto movería el valor de firstName a una nueva propiedad llamada first_name y eliminaría la antigua propiedad firstName.

5. La operación copy

La operación copy copia un valor de una ubicación a otra. El valor original permanece sin cambios.

Crear una copia de seguridad de una configuración:

{ "op": "copy", "from": "/preferences/theme", "path": "/backupTheme" }

Esto copia el valor del tema actual a un nuevo campo backupTheme.

6. La operación test

Esta es una característica de seguridad. La operación test verifica que un valor en una ubicación sea igual a un valor especificado. Si la prueba falla, todo el parche se aborta. Esto es increíblemente útil para prevenir conflictos (bloqueo optimista).

Asegurarse de que nadie más haya cambiado el correo electrónico antes de actualizarlo:

[
  { "op": "test", "path": "/email", "value": "john.old@example.com" },
  { "op": "replace", "path": "/email", "value": "john.new@example.com" }
]

Si el email actual no es "john.old@example.com" (quizás otro proceso ya lo cambió), la operación test falla, y el replace nunca ocurre. Esto asegura que tu actualización se base en el último estado conocido.

¿Por qué usar JSON Patch? Los beneficios

1. Eficiencia: El beneficio más obvio. Solo envías los cambios, lo que reduce significativamente el tamaño de la carga útil y mejora el rendimiento.
2. Control de Concurrencia: La operación test proporciona un mecanismo incorporado para el bloqueo optimista, ayudándote a evitar actualizaciones perdidas y condiciones de carrera.
3. Atomicidad: La naturaleza de todo o nada de una aplicación de parche asegura que tus datos permanezcan consistentes. Si la quinta operación en un parche de diez operaciones falla, las primeras cuatro se revierten.
4. Claridad e Intención: El cuerpo de la solicitud describe claramente la intención del cambio ("reemplazar el correo electrónico", "añadir un pasatiempo") en lugar de simplemente volcar un nuevo estado. Esto hace que los registros sean más legibles y la depuración más fácil.
5. Estandarización: Es un estándar IETF (RFC 6902). Otros desarrolladores lo reconocerán, y muchas bibliotecas y frameworks en diferentes lenguajes de programación tienen soporte incorporado para analizar y aplicar documentos JSON Patch.

Errores comunes y trampas con JSON Patch

Aunque JSON Patch es potente, los desarrolladores a menudo se encuentran con estos problemas:

• Usar la ruta incorrecta (errores de sintaxis de JSON Pointer).
• Olvidar campos obligatorios como value o from.
• Aplicar parches a rutas inexistentes.
• Abusar incorrectamente de las operaciones test.
• Confundir JSON Patch con JSON Merge Patch.

Por qué las API usan JSON Patch

Las API adoran JSON Patch porque es:

• Eficiente: Envía solo lo que ha cambiado.
• Atómico: Múltiples cambios en una sola solicitud.
• Flexible: Admite operaciones avanzadas como mover/copiar.
• Estandarizado: Funciona en diferentes sistemas.

Por ejemplo, la API de GitHub admite JSON Patch para editar metadatos del repositorio de manera eficiente.

JSON Patch en las API REST

En las API RESTful, JSON Patch se utiliza a menudo con el método HTTP PATCH.

PATCH vs PUT:

• PUT reemplaza todo el recurso.
• PATCH actualiza parte del recurso.

Con JSON Patch, el Content-Type es:

application/json-patch+json

Esto le indica al servidor que el cuerpo contiene un documento JSON Patch.

JSON Patch en GraphQL y otros protocolos

Aunque JSON Patch se utiliza principalmente en las API REST, también tiene relevancia en:

• Mutaciones de GraphQL: Aplicando actualizaciones incrementales.
• gRPC con cargas útiles JSON: Enviando parches estructurados.
• Arquitecturas basadas en eventos: Transmitiendo solo cambios en lugar de objetos completos.

Cómo JSON Patch mejora la eficiencia

Imagina una aplicación móvil sincronizando perfiles de usuario. En lugar de volver a subir un archivo JSON de 2 MB para cada pequeña actualización, la aplicación puede simplemente enviar una pequeña solicitud de parche.

Esto significa:

• Tiempos de sincronización más rápidos.
• Menor uso de datos móviles.
• Mejor rendimiento del servidor.

Desafíos y consideraciones

JSON Patch es potente, pero no está exento de complejidades.

1. Implementación Compleja en el Servidor: Aplicar un parche correctamente en el servidor es más complejo que simplemente aceptar un nuevo objeto JSON. Necesitas validar cada operación, manejar apropiadamente los punteros a rutas inexistentes y asegurar que toda la secuencia se aplique atómicamente. Afortunadamente, la mayoría de los frameworks web modernos tienen bibliotecas para manejar esto por ti (por ejemplo, json-patch para Node.js, jsonpatch para Python, JsonPatchDocument en .NET).
2. Potencial de Errores: Un documento de parche mal formado o un puntero inválido (por ejemplo, intentar replace un campo que no existe) resultará en un error. Tu API debe manejar estos errores con gracia y devolver mensajes de error claros (generalmente un 422 Unprocessable Entity o 400 Bad Request).
3. No es una Panacea: Para recursos muy simples, un PUT podría ser más simple. JSON Patch brilla cuando tus recursos son grandes o cuando necesitas admitir actualizaciones complejas y condicionales.

Probando el endpoint JSON Patch con Apidog

Probar JSON Patch manualmente puede ser frustrante. Aquí es donde una herramienta API sofisticada se vuelve invaluable. Apidog, una plataforma de desarrollo de API todo en uno, puede ser de gran ayuda aquí:

• Pruebas: Puedes probar fácilmente el endpoint PATCH en un panel visualizado y obtener los resultados de validación de la respuesta.
• Documentación: Puedes documentar tus endpoints PATCH dentro de Apidog, mostrando claramente a otros miembros del equipo el formato esperado, lo que mejora la colaboración y reduce los errores de integración.

Ejemplo de flujo de trabajo en Apidog:

1. Crea una nueva solicitud.
2. Establece el método en PATCH.
3. Añade Content-Type: application/json-patch+json.
4. Introduce tu array JSON Patch.
5. Envía y verifica los resultados al instante.

Al usar Apidog, pasas de adivinar si tu parche es correcto a saber que está bien construido, lo que te permite implementar y consumir API JSON Patch con confianza y empezar a probar JSON Patch como un profesional.

Mejores prácticas de JSON Patch

Para usar JSON Patch de manera efectiva:

1. Valida tus documentos JSON Patch antes de enviarlos.
2. Usa operaciones de prueba cuando la consistencia sea importante.
3. Mantén los parches pequeños para mayor eficiencia.
4. Documenta tu API claramente cuando uses JSON Patch.
5. Usa herramientas como Apidog para optimizar las pruebas.

Conclusión: Adoptando un estándar de API más eficiente

Entonces, ¿qué es JSON Patch?

Es una forma estandarizada de describir cambios en documentos JSON utilizando operaciones como añadir, eliminar y reemplazar. En lugar de enviar objetos completos, puedes enviar solo los cambios, haciendo tus API más eficientes, fiables y flexibles.

JSON Patch transforma la forma en que pensamos sobre la actualización de datos a través de las API. Nos mueve del instrumento contundente de la sustitución de documentos completos a la precisión de los cambios quirúrgicos. Al adoptar este estándar, construimos API que son más eficientes, menos propensas a conflictos y más claras en su intención.

Aunque requiere un poco más de reflexión inicial en el lado del servidor, los beneficios para las aplicaciones cliente y el rendimiento de la red son sustanciales. La próxima vez que te encuentres diseñando un endpoint de actualización, resiste el PUT predeterminado y pregúntate: "¿Podría ser esto un trabajo para PATCH?"

Para los desarrolladores, comprender JSON Patch es clave para trabajar con API modernas, especialmente al manejar actualizaciones parciales. Y con herramientas como Apidog, puedes probar, validar y depurar solicitudes JSON Patch con facilidad.