Diff de respuesta de API: compara payloads JSON de API en línea
Pega la respuesta que esperabas a la izquierda, la respuesta que realmente recibiste a la derecha, y verás cada campo que cambió. Pensado para trabajo de backend, QA e integración. Nada sale de tu navegador.
Qué es esta herramienta de diff de respuesta de API
Una herramienta gratuita y dentro del navegador para comparar dos cuerpos de respuesta HTTP de API. Pega el JSON que obtuviste de staging a la izquierda, el JSON de producción a la derecha, y las diferencias se resaltan carácter por carácter. El texto nunca sale de tu equipo, lo que importa porque las respuestas reales de API contienen con frecuencia direcciones de email de clientes, tokens de sesión, IDs internos de usuario, y otras cosas que no quieres subir a un sitio externo de diff.
Está pensado para ese momento en que un test de integración inestable falla en CI, y tienes una captura de Postman de una respuesta correcta en tu portátil y un log de CI de una respuesta rota desde el runner. Montar un contract test de Pact completo para una investigación puntual es excesivo. Dos paneles de texto, un diff, y normalmente puedes acotarlo a un único campo en menos de un minuto.
Por debajo, el motor de diff es el mismo que utiliza nuestra herramienta compare-json. Solo lo hemos enmarcado para el flujo de testing de API. Si tus respuestas son XML o sobres SOAP, nuestra página compare-xml los gestiona. Si comparas texto libre como un log de webhook o un audit trail, nuestra herramienta compare-text es la superficie correcta.
Cómo ayuda realmente un diff de respuesta de API
Un diff de respuesta de API se sitúa en el hueco entre dos ideas de testing relacionadas pero distintas. El diff de schema OpenAPI 3.1 te dice qué declara tu contrato que cambió: un nuevo campo opcional, una propiedad renombrada, un enum más estricto. El snapshot testing (snapshots de Jest, snapshots de Vitest, pytest-snapshot) te dice qué produjo tu código frente a un fixture guardado. Esta herramienta vive en el lado del runtime. Le das dos cuerpos de respuesta reales y te muestra cada byte que difiere, sin importar si el schema permite el cambio o si tu fixture de snapshot está actualizado.
¿Por qué es útil? Porque los bugs que más duelen en el trabajo de integración REST no son violaciones de schema. Son derivas sutiles: un serializer que cambió silenciosamente una fecha de ISO-8601 a un timestamp Unix tras una actualización de Jackson, un schema de Marshmallow que empezó a emitir null en lugar de omitir un campo ausente, un ViewSet de DRF que comenzó a envolver el payload en un sobre data tras un cambio de middleware. La spec de OpenAPI no cambió. El snapshot no se actualizó. Los tests pasaron en aislamiento. La integración se rompió. Un diff de cuerpo de respuesta detecta todos estos casos porque no le importa el contrato; le importan los bytes.
Los campos volátiles son lo principal a vigilar. Timestamps, request IDs, trace IDs, UUIDs generados por el servidor y cursores de paginación diferirán entre dos capturas cualesquiera del mismo endpoint, incluso cuando nada relevante haya cambiado. Lo correcto es normalizar antes del diff: sustituye los timestamps por un placeholder, elimina trace IDs, ordena los arrays cuyo orden no sea contractualmente significativo. Herramientas como Pact lo gestionan con matchers; en esta herramienta lo gestionas editando los paneles. Lleva diez segundos y elimina el ruido de fondo.
Cómo hacer diff de una respuesta de API en tres pasos
Dos paneles de texto, un diff. Sin login, sin subida, sin proxy que cablear.
- 1
Captura la primera respuesta
Llama al endpoint con curl, httpie, Postman, Insomnia, o lo que use tu equipo. curl -s https://api.example.com/v1/users/123 | jq es una buena base porque jq da formato legible al JSON, lo que hace mucho más fácil leer el diff. Copia el cuerpo (solo el JSON, no las cabeceras) y pégalo en el panel izquierdo. Si lo sacas de un log de CI, quita el prefijo de timestamp que añaden la mayoría de loggers para que el diff caiga sobre el payload real.
- 2
Captura la segunda respuesta
Llama a la fuente de comparación: el otro entorno, la otra versión de API, el otro proveedor. Misma forma de captura, mismo paso de pretty-print. Pégala en el panel derecho. Si una captura proviene de un fixture grabado (vcrpy, pollyjs, MSW, nock) y la otra es en vivo, normaliza primero los campos volátiles obvios: limpia el request_id, sustituye los timestamps por una constante, y quita las cabeceras de trace que se hayan colado en el cuerpo. El diff restante es la señal real.
- 3
Lee las diferencias resaltadas
Las eliminaciones aparecen como tachados rojos a la izquierda; las inserciones como verde a la derecha. Los contadores de cambios en cada cabecera te dicen cuántas ediciones distintas encontró el diff. Céntrate primero en tres cosas: cambios en cadenas de status, claves añadidas o ausentes, y cambios de tipo de valor (string a número, objeto a null). Esas tres categorías cubren casi cualquier regresión real de API. Los cambios de formato y orden suelen ser ruido salvo que tu consumer dependa de ellos.
Cuándo un diff de respuesta de API es la opción correcta
Reproducir un test de integración inestable
Un test pasa en local y falla en CI. Tienes la respuesta capturada por tu Postman local y la respuesta capturada por el agente de build de CI (la mayoría de sistemas de CI permiten volcar request/response con un flag verbose). Pega ambas en la herramienta de diff. Nueve de cada diez veces la diferencia es algo del entorno: un feature flag distinto, un fixture obsoleto, un offset de zona horaria en el runner. La que queda es un bug real, y acabas de localizarlo en un campo concreto.
Validar un fixture frente a una respuesta nueva
Tu repo tiene un fichero de fixture comprometido que mockea una API de terceros para los tests. El proveedor upstream acaba de publicar una versión menor. Llama al endpoint en vivo con curl, pega esa respuesta junto a tu fixture, y verás exactamente qué campos derivaron. Esta es la versión manual de lo que automatizan las herramientas de replay tipo VCR. Útil cuando quieres actualizar un fixture sin volver a grabar toda tu suite de tests.
Verificar la compatibilidad hacia atrás entre versiones de API
Estás a punto de publicar la v2 de una API interna. Aún existe un cliente v1 en producción. Llama tanto a /v1/orders/42 como a /v2/orders/42 y haz el diff de las respuestas. Cualquier campo eliminado, cualquier clave renombrada, cualquier cambio de tipo de valor es un cambio incompatible para el cliente v1. Cualquier campo nuevo es aditivo y seguro. Es una versión de andar por casa de un contract test impulsado por el consumer; no escala a docenas de endpoints, pero para una comprobación rápida de uno o dos funciona.
Detectar una regresión de serializer
Tu equipo actualizó Jackson, Marshmallow, DRF, o una capa de serialización similar. Los tests pasan. Después un consumer downstream avisa de que su parser se atraganta. Captura la respuesta del mismo endpoint en la rama antigua y en la nueva y haz el diff. Hallazgos comunes: un formato de fecha cambió de 2026-05-09T10:00:00Z a un timestamp Unix, los decimales perdieron ceros finales, un enum empezó a serializarse como entero en vez de string, o aparecen campos null en el payload que antes se omitían.
Comparar payloads de webhook entre dos proveedores o versiones
Los webhooks V1 y V2 de Stripe del mismo tipo de evento parecen casi idénticos y no lo son ni de lejos. Lo mismo con los payloads de eventos de webhook de GitHub entre versiones de API, y con las suscripciones de eventos de Slack entre scopes. Pega un payload de muestra de cada uno en la herramienta de diff para ver los campos renombrados, los objetos anidados movidos, y los nuevos bloques de metadatos. Es más rápido que leer las dos páginas de doc del proveedor en paralelo, especialmente cuando la doc pasa por encima de qué campos aparecen realmente en la práctica.
Depurar el clásico "funciona en staging, roto en prod"
El dolor de cabeza clásico del despliegue. La misma petición del cliente devuelve JSON sutilmente distinto desde staging y producción. Captura ambas, pega ambas, y la diferencia suele ser un flag de configuración, un feature gate ausente, o una respuesta cacheada antigua. Esto se aplica igual al debugging multi-región (us-east-1 vs eu-west-1 devolviendo datos distintos), problemas de caché de CDN (Cloudflare cacheó un cuerpo antiguo), y lag de réplicas de lectura donde una escritura no se ha propagado a todas partes.
Casos límite del diff de respuesta de API que conviene conocer
Los casos en los que un diff de cuerpo de respuesta no coincide con lo que dirían tu framework de tests, tu herramienta de OpenAPI, o tus ojos. Vale la pena revisarlos antes de asumir que el diff ha encontrado un bug real.
| Topic | What this tool does |
|---|
| Campos volátiles (timestamps, IDs) | created_at, updated_at, request_id, trace_id, los UUIDs generados por el servidor y los cursores de paginación siempre diferirán entre dos capturas. Normalízalos con jq 'del(...)', sustitúyelos por una constante, o simplemente edítalos antes del diff. La señal que de verdad importa vive en otra parte. |
|---|
| null vs clave ausente | {"foo": null} y {} son distintos en JSON, y muchos serializers (Marshmallow, Jackson, System.Text.Json) tienen ajustes que alternan entre ambos. El diff lo sacará a la luz. Algunos clientes los tratan como equivalentes y otros no; la respuesta correcta es lo que haga tu consumer, y por eso es una fuente frecuente de regresiones tras una actualización de serializer. |
|---|
| Orden de claves | RFC 8259 define los objetos JSON como desordenados. Dos respuestas semánticamente idénticas con distinto orden de claves mostrarán diferencia aquí porque la comparación de texto es sensible al orden. Pre-ordena ambos lados con jq --sort-keys si quieres un diff insensible al orden. Cuidado con el raro consumer que sí dependa del orden (algunos flujos de firma, algunos parsers legacy). |
|---|
| Orden de arrays | Los arrays en JSON son ordenados, pero muchas APIs devuelven arrays cuyo orden no es contractual: una lista de permisos, una lista de feature flags, una lista de suscripciones a webhooks. Un diff marcará un array reordenado como cambio aunque a ningún consumer le importe. Si reordenar es inocuo en tu dominio, ordena ambos lados por una clave estable antes del diff. |
|---|
| Estrictez de JSON.parse | El diff trata tu entrada como texto opaco. Si una de tus capturas tiene una coma final, una clave sin comillas, o un comentario (todos ilegales en JSON estricto), el diff seguirá funcionando pero se verá más ruidoso de lo necesario. Pasa ambas capturas por jq . primero para reformatear y rechazar entrada no válida. jq usa un parser estricto de RFC 8259. |
|---|
| Envolturas de respuesta (sobre data vs plano) | Muchas APIs envuelven los payloads en un sobre {"data": ...}, a veces añadiendo meta, links, o included al lado (JSON:API y similares). Una migración de plano a envuelto (o al revés) es un cambio incompatible que aparece de inmediato en un diff pero es fácil de pasar por alto en una revisión de schema porque el registro subyacente parece el mismo. |
|---|
| Cambios de cursor de paginación | La paginación basada en cursor usa tokens opacos (next_cursor, after, page_token) diseñados para cambiar en cada llamada. Siempre aparecerán como diferencia. Quítalos antes de comparar, o compara solo el contenido del array data e ignora el bloque de paginación por completo. |
|---|
| Formatos de respuesta de error | Los cuerpos de error son el oeste salvaje. Algunas APIs devuelven un {"error": "..."} plano, otras devuelven RFC 7807 Problem Details con type, title, status, detail, instance, y otras devuelven una forma propia del proveedor. Una migración a RFC 7807 desde una forma propia producirá un diff grande que es en su mayoría una mejora; una migración en sentido contrario es una regresión que conviene detectar pronto. |
|---|
Diff de respuesta de API: preguntas frecuentes
¿En qué se diferencia esto de la función de diff integrada de Postman?
Postman tiene una vista de comparación de respuesta dentro de su Collection Runner y una función Visualize para respuestas individuales. Ambas son buenas si vives dentro de Postman y tus respuestas ya están guardadas como entradas de historial. Esta herramienta es agnóstica al proveedor. Puedes pegar desde Postman, Insomnia, curl, httpie, un log de CI, un snippet de Stack Overflow, o el mensaje de Slack de un compañero. No hay cuenta, ni workspace, ni sync. Para comparaciones puntuales entre herramientas, eso es más rápido. Para testing de API compartido en equipo dentro de una sola plataforma, la función propia de Postman está bien.
¿Cómo manejo campos volátiles como timestamps y request IDs?
Lo pragmático es normalizar antes del diff. Abre ambos pegados en los paneles, y luego edita los campos volátiles directamente: sustituye los timestamps por una cadena constante, quita los valores de request_id y trace_id, elimina los cursores de paginación que cambian en cada llamada. El diff resalta solo las diferencias restantes, que son las que importan de verdad. Para comparaciones repetidas del mismo endpoint, también puedes pasar la respuesta por jq con un filtro de borrado (jq 'del(.meta.request_id)') antes de pegar.
¿En qué se diferencia esto de un diff de schema OpenAPI?
El diff de schema compara contratos: te dice que POST /orders añadió un campo opcional discount_code, o que el enum status ganó un nuevo valor. Las herramientas conscientes de OpenAPI como oasdiff o Spectral lo hacen bien. Esta herramienta compara cuerpos de respuesta reales. Las dos son complementarias. El diff de schema captura cambios de contrato; el diff de respuesta captura la deriva entre el contrato y la realidad, que es donde se esconden los bugs de serialización, los desajustes de entorno y los fixtures obsoletos.
¿Soporta respuestas grandes?
En la práctica sí, hasta unos pocos miles de líneas de JSON con formato a cada lado. Más allá de eso, el diff a nivel de carácter con limpieza semántica se ralentiza porque corre en tu navegador, no en un servidor. Para payloads muy grandes (piensa en un volcado paginado de 10.000 registros), lo correcto es trocear la respuesta en piezas más pequeñas por registro o por clave de nivel superior y hacer diff de cada pieza por separado. O ejecutar un diff estructural en línea de comandos con jd o diff <(jq . a.json) <(jq . b.json) para velocidad pura.
¿Funciona para respuestas XML o SOAP?
Directamente no. Esta página está afinada para JSON, que es lo que usan la mayoría de payloads modernos REST y de webhook. Si necesitas hacer diff de XML, sobres SOAP, RSS, o configuración estilo POM, nuestra herramienta compare-xml es la superficie correcta; gestiona la indentación y el formato de namespaces correctamente. Para cuerpos de respuesta crudos que mezclan cabeceras y cuerpo, o para APIs de texto plano (algunos sistemas legacy todavía devuelven text/plain), compare-text hace el trabajo sin tratar de imponer una estructura.
¿Conserva el orden de claves o las ordena?
Conserva el orden de claves que pegues. Los objetos JSON están formalmente desordenados según RFC 8259, así que dos respuestas semánticamente idénticas con claves en distinto orden mostrarán diferencia en esta herramienta. Si quieres ignorar el orden, normaliza ambos lados primero pasándolos por jq --sort-keys o equivalente. La mayoría de clientes no dependen del orden de claves, así que la normalización por claves ordenadas es un valor por defecto seguro para comparar respuestas; ten en cuenta que algunos consumers legacy (puentes XML-a-JSON antiguos, ciertos flujos de firma digital) sí dependen del orden.
Privacidad y por qué importa para las respuestas de API
Los payloads de respuesta de API contienen con frecuencia cosas que no quieres filtrar. Direcciones de email de clientes. IDs internos de usuario. Tokens de sesión. Tokens bearer de auth que acabaron en un campo del cuerpo por error. IDs de cliente de Stripe. Secretos de webhook. Campos PII como nombres, direcciones y teléfonos. Pegar uno en un servicio de diff alojado en la nube es en sí mismo un evento de tratamiento de datos, y según tu sector puede vulnerar tus controles SOC 2, los acuerdos de tratamiento de datos GDPR, o los Business Associate Agreements de HIPAA. Esta herramienta corre íntegramente en tu navegador. No se sube, registra ni envía nada a ningún servicio externo. El diff, el resaltado y el renderizado se ejecutan en tu equipo. Verificarlo es directo: abre las DevTools de tu navegador, ve a la pestaña Network, pega ambas respuestas, y observa. No hay peticiones salientes al comparar. Para guías más amplias de diseño y seguridad de API, las buenas prácticas de diseño de API de Microsoft son una referencia sólida.