Herramientas de depuración de API: las seis pestañas que abro cuando me miente un punto final

Un punto final de activación de licencia en uno de mis proyectos de Laravel comenzó a rechazar cada token que se entregó. No algunas fichas. Cada token, incluidos los que el mismo servidor había emitido noventa segundos antes. Los registros dijeron token expired. Las fichas no estaban vencidas. Pasé la mayor parte de un sábado convencido de que el reloj de la caja había desviado.

No tenía'No. El error era una línea:

if (payload.exp < Date.now()) throw new Error('token expired')

exp en un JWT es artículos de segunda clase desde la época, RFC 7519 §4.1.4 no tiene ambigüedades al respecto. Date.now() En devoluciones de JavaScript milisegundos. Así que estaba comparando un número de diez dígitos con un número de trece dígitos y los números de diez dígitos siempre son más pequeños. Cada ficha del universo ha expirado, para siempre. la solución fue Date.now() / 1000. El diagnóstico tomó ocho horas porque en realidad nunca aparente en el token, seguí releyendo mi propio código, que es el equivalente de depuración de buscar tus gafas mientras las usas.

Lo que finalmente rompió el bucle fue pegar el token en un decodificador, leyendo exp: 1748952000, convirtiendo eso en una fecha y viendo una marca de tiempo dos semanas en el futuro. La ficha estaba bien. Mi comparación fue incorrecta. Treinta segundos de mirar datos superaron las ocho horas de mirar el código.

Eso's de qué se trata esta guía. No es una filosofía de depuración inteligente: las herramientas de navegador específicas, aburridas y poco glamorosas que guardo en un grupo de pestañas llamado "API Debug," para qué sirve realmente cada uno y los modos de falla que captan. Aquí todo se ejecuta en el lado del cliente Toolz.dev, lo que importa más de lo que parece cuando lo que estás a punto de pegar es un token de portadora de producción.

TL;Dr: Cuando una API se porte mal, deje de leer su código y comience a leer la carga útil. Formatea la respuesta con el Formateador JSON. Rompe la ficha con el Decodificador JWT, no es una herramienta base64 genérica. desmayo exp, iaty X-RateLimit-Reset en fechas reales con el Convertidor de marca de tiempo. Compare una respuesta de trabajo con una rota con la Diferencia de texto O mejor, el Diferencia de JSON. Decodificar la serie de consultas de cadenas con el Codificador de URL. Todo se ejecuta en su navegador; el token nunca pasa por el cable.

¿Por qué la depuración de una API se siente mucho peor que la depuración del código?

Porque no puedes pasar por él. Un error local tiene un seguimiento de pila, un depurador y un punto de interrupción. Un error de API tiene una cadena. El servidor de alguien más produjo esa cadena, según reglas que solo conoces a la mitad, y tu trabajo es trabajar hacia atrás.

Eso invierte la habilidad habitual. El cuello de botella no es lógica, es legibilidad. Casi todos los errores de API que he perseguido en los últimos años fueron invisibles hasta que hice que los datos fueran legibles:

• Una respuesta JSON de 4000 caracteres minificada que resultó tener "data": null enterrado en la profundidad seis.
• Una carga útil Base64 que decodificó en un mensaje de error La API fue demasiado educada para poner en el código de estado.
• Un webhook que falló la verificación de firma porque el cuerpo tenía una nueva línea de mi cliente HTTP que estaba agregando de manera útil.
• Una marca de tiempo que fue en milisegundos cuando los documentos dijeron segundos. (dos veces. diferentes empresas.)

Ninguno de estos eran problemas difíciles. Todos ellos fueron ilegible Problemas. Las herramientas a continuación existen para hacer que los datos sean lo suficientemente legibles como para que note lo que sus ojos pasarían de otro lado.

¿Qué herramienta para qué síntoma?

Esta es la mesa que desearía que alguien me hubiera entregado hace cinco años. Síntoma a la izquierda, primero moverse a la derecha.

Todo lo que sigue es la versión larga de esa mesa.

¿Cómo hago que una respuesta de API sea legible en diez segundos?

Pégalo en el Formateador JSON. Eso' es toda la técnica, y yo' No estoy siendo simplista: el hábito de depuración de mayor apalancamiento que tengo es negarme a hacerlo razonar Una carga útil no he formateado.

Aquí hay una forma de respuesta que obtengo de un proveedor de facturación, exactamente como se desprende:

{"subscriptions":[{"id":"sub_7f3d8a2b","status":"active","plan":{"id":"pro_annual","interval":"year","amount":9900},"current_period_end":1748952000,"cancel_at_period_end":false}],"has_more":false}

Formateado, es un objeto completamente diferente, no para el analizador, sino para mí:

{
  "subscriptions": [
    {
      "id": "sub_7f3d8a2b",
      "status": "active",
      "plan": {
        "id": "pro_annual",
        "interval": "year",
        "amount": 9900
      },
      "current_period_end": 1748952000,
      "cancel_at_period_end": false
    }
  ],
  "has_more": false
}

Ahora puedo ver eso amount es 9900 y no 99.00- it's en centavos, que es el error de integración más común en los pagos, y eso current_period_end es un número entero de diez dígitos, lo que significa segundos, lo que significa que no se lo entregues a new Date() directamente.

La validación atrapa lo que tus ojos no quieren

El formato también valida. Un fracaso de análisis es la información. Los errores que realmente aparecen en cargas reales:

• comas de arrastre. Legal en JavaScript, ilegal en JSON (por RFC 8259). Los accesorios editados a mano están llenos de ellos.
• Cotizaciones individuales. JSON requiere comillas dobles. str(dict) La salida no es JSON, no importa cuánto lo parezca.
• Claves no cotizadas. La misma historia - eso' es un objeto JavaScript literal, no JSON.
• NaN / Infinity. Algunos serializador los emiten. JSON no tiene tales literales.
• un nacido. una marca de orden de bytes UTF-8 delante de { Hará que un analizador estricto rechace un documento que se ve perfecto en la pantalla.

Si su JSON es válido pero el formular está mal, eso' es una herramienta diferente; consulte la sección de diferencias a continuación.

¿Por qué usar un decodificador JWT en lugar de solo decodificar el token de base64?

Puede decodificar un JWT a mano. Lo hice durante años. Es un mal hábito, y aquí por qué.

Un JWT (RFC 7519) es tres fragmentos separados por puntos: encabezado, carga útil, firma. Cada trozo es Base64url, nu basic64 standard - RFC 4648 §5, el alfabeto seguro para URL que intercambia +→- y /→_ y por lo general deja caer el = Relleno. Aliméntalo a un decodificador estándar-base64 estricto y le dará bytes de basura en silencio. Por lo tanto, el método de la mano significa dividir los puntos, volver a rellenar e intercambiar el alfabeto, cada vez, y luego observar RAW JSON.

los Decodificador JWT hace todo eso en una sola pasta y, la parte que realmente ahorra tiempo, presenta las reclamaciones como reclamaciones. Los que compruebo, en orden:

• exp (caducidad) y iat (emitido en) - ambos Fecha numérica, es decir artículos de segunda clase Desde 1970-01-01 UTC. Este es el campo que se comió mi sábado.
• aud (audiencia): un token creado para su API de preparación será estructuralmente perfecto y aún así será rechazado por prod.
• iss (emisor) - después de una migración de proveedor de identidad, este es el campo que cambió silenciosamente.
• alg en el encabezado, si dice none, Tiene un problema de seguridad, no un problema de depuración.

Tome el token de ejemplo canónico que todos han visto:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Encabezado: {"alg":"HS256","typ":"JWT"}. Carga útil: {"sub":"1234567890","name":"John Doe","iat":1516239022}. y iat hay 2018-01-18T01:30:22Z- que sólo sabes ejecutándolo a través de un convertidor de marca de tiempo, que es el objetivo de la siguiente sección.

lo que un decodificador no hace

La decodificación no está verificada. Cualquiera puede decodificar un JWT; la carga útil está codificada, no encriptada. Un decodificador te dice lo que la ficha demanda, nunca si la afirmación es cierta. La verificación de firma ocurre en su servidor con su secreto, y nunca se debe entregar ese secreto a ninguna herramienta de navegador. Trate a un JWT decodificado de la forma en que tratará una presentación de formulario: como una afirmación de un extraño.

¿Cómo dejo de equivocarme las marcas de tiempo?

Aprende a leer el recuento de dígitos. Esta es la habilidad de depuración más barata en todo el campo y se necesita un minuto para aprender.

Diez dígitos significa segundos. Trece significa milisegundos. JavaScript Date Constructor quiere milisegundos; UNIX, Python time.time(), Vaya Unix(), php'S time(), y la mayoría de las API' exp Los campos hablan segundos. Todo aguas abajo de ese desajuste es un caos.

Y el caos es ruidoso en una dirección y silencioso en la otra. pienso artículos de segunda clase a un analizador de milisegundos y obtienes 1970, un error tan obvio que lo solucionas en un minuto. Alimentar milisegundos a un artículos de segunda clase Analizador y obtienes el año 56122. revisé: 1708876200000, interpretado como segundos, aterriza el 17 de febrero del año 56122. Eso' es la dirección que se envía silenciosamente, porque nada se lanza: una suscripción simplemente nunca caduca y nadie se da cuenta durante un trimestre.

los Convertidor de marca de tiempo existe para que puedas resolver esto en una pasta en lugar de discutir sobre ello. masa 1748952000, lea la fecha, siga adelante. pegar el X-RateLimit-Reset Encabezado Su API se está quejando y descubra que tiene cuatro minutos para esperar, no cuatro horas. Si la marca de tiempo es ingenua (no Z, sin compensación) y necesita razonar sobre lo que significa en otra región, el Convertidor de zona horaria es el seguimiento.

Dos trampas más de marca de tiempo que vale la pena conocer

El problema de 2038 es real y anticuado. Un contador de segundos de 32 bits con signo se desborda en 2147483647, que es 2038-01-19T03:14:07Z. Cualquier sistema que aún almacene tiempo en un int firmado de 32 bits, y hay más de ellos en columnas de bases de datos integradas y heredadas de lo que nadie quiere admitir, se rompe entonces. Si usted 'Estás estableciendo vencimientos de larga duración hoy, ya puedes lograr esto.

Las marcas de tiempo ingenuas son una mentira por omisión. 2026-02-25T14:30:00 sin rastreo Z y no +05:30 No es un momento en el tiempo; es un momento en un lugar no especificado. Trato cualquier API que devuelva marcas de tiempo ingenuas como un informe de error que espera ser archivado. Prefiero RFC 3339 (2026-02-25T14:30:00Z), que es el perfil estricto e inequívoco de la ISO 8601 que la web utiliza realmente.

¿Qué hago cuando "funcionó ayer"?

Diferenciarlo. Don't teorizar - diferenciarlo.

Capture la respuesta del entorno de trabajo (o saque la última buena de sus registros) y la respuesta del roto, y póngalos uno al lado del otro. Nueve de cada diez veces hay exactamente una diferencia y te está mirando en cinco segundos.

Para JSON, busque el Diferencia de JSON antes de la diferencia de texto. Analizó ambos lados y compara estructurar, lo que significa claves reordenadas y sangría diferente don' No aparecen como cambios, solo aparecen los reales. Una diferencia de texto de dos documentos JSON que un servidor serializado en un orden de clave diferente se iluminará como un árbol de Navidad y no le dirá nada.

Para todo lo que es't JSON - encabezados, cuerpos sin procesar, archivos de configuración, curl salida: utilice el Diferencia de texto. Su especialidad es la clase de cambio que tus ojos son físicamente incapaces de atrapar: un espacio final, una pestaña que se convirtió en cuatro espacios, una línea CRLF que se coló de una máquina con Windows, una cita rizada que un sitio de documentación sustituía por una recta cuando copiaste el ejemplo. He escrito una pieza completa sobre Por qué fallan las comparaciones de texto alucinantes, porque me costó una escalada de apoyo una vez.

¿Por qué los parámetros de mi consulta siguen llegando rotos?

Porque la codificación de URL tiene tres o cuatro sabores sutilmente diferentes y la pila de todos elige uno diferente.

Los clásicos, en orden áspero de la frecuencia que me han mordido:

• + frente contra %20. En una cadena de consulta, + Históricamente significa un espacio (el application/x-www-form-urlencoded convención). En un segmento de ruta, + Significa una ventaja literal. Entonces, una firma Base64 que contiene +, se deja caer en una cadena de consulta sin codificar, llega con espacios y la verificación de firma falla. Esta es una verdaderamente desagradable porque el valor acecharse Justo en los registros.
• Codificación doble. %2F se convierte en %252F Porque dos capas de su pila lo codificaron de manera útil. El síntoma es un parámetro que gana porcentaje-señal cada vez que pasa a través de un proxy.
• un crudo & dentro de un valor. Divide su parámetro en dos. hoy día name=Ben & Jerry es name=Ben Además de un parámetro de misterio llamado Jerry.

Pegue la URL en el Codificador de URL y decodificarlo. Si decodificarlo una vez todavía deja escapar el porcentaje de escape, has encontrado tu codificación doble. Ese es el diagnóstico completo.

¿Cómo depurar un webhook que no verifique?

Este es el que separa "Entiendo HTTP" de "He estado de guardia".

Casi todos los proveedores de webhook firman la carga útil con un HMAC y ponen el resultado en un encabezado. Su trabajo es calcular el mismo HMAC y comparar. Cuando no coincide, la firma casi nunca es el problema. Los bytes son el problema. No estás hachándole lo que hash.

Los sospechosos habituales:

1. Has pulido el cuerpo analizado y re-serializado. Su marco analizó el JSON en un objeto, a la que llamó JSON.stringify() en él, y ahora el orden de las teclas o el espacio en blanco difiere en un carácter. Debes hachizar el tosco Cuerpo de solicitud, bytes como se recibe. En Express, eso significa capturar el búfer sin procesar antes express.json() llega a ella; en Laravel significa $request->getContent(), no $request->all().
2. Una nueva línea. Algunos clientes agregan uno. El proveedor no.
3. Usted está hash la cadena codificada hexadecimal en lugar de los bytes sin formato, o comparar hexadecimal con base64.
4. juego de charles. El cuerpo tiene un carácter de varios bytes y algo en el camino lo transcodificó.

los generador de hachas Así es como aíslo esto: tome la cadena exacta del cuerpo, la hash, compare con lo que produje mi código para lo que reflexión era el mismo cuerpo. Si esos dos hashes difieren, mi código no está viendo los bytes, creo que se ve, y el problema nunca fue criptográfico en absoluto. (También vale la pena saberlo: si un proveedor todavía ofrece firmas MD5 o SHA-1, esa es una señal sobre la edad de su plataforma. SHA-256 es el piso ahora.)

¿Qué más vive en el grupo de pestañas de depuración?

El reparto secundario, menos glamoroso, todavía se gana su lugar:

• generador de UUID- por una limpieza X-Request-ID En cada llamada de prueba, para que puedas obtenerla en tres registros de servicios después. Vale la pena saber que los UUID obtuvieron una actualización de especificaciones: RFC 9562 (2024) obsoleto RFC 4122 y estandarizado uuidv7, que es ordenado por el tiempo y, por lo tanto, mucho más amable con su índice de árbol B que aleatorio v4. Si está eligiendo un esquema de identificación para una nueva tabla hoy, esa es la que debe leer. hay un Desglose más largo de las versiones de UUID Si lo quieres.
• Convertidor Base64- pentru Authorization: Basic Encabezados (RFC 7617: It'S base64(user:password), y sí, eso 's codificación, no seguridad - TLS es lo que la protege), y para los blobs binarios en línea, algunas API se incluyen en campos JSON. Base64 le cuesta ~33% de sobrecarga de tamaño, razón por la cual " inesperadamente grande" La carga útil a menudo solo tiene un archivo. El Guía completa de base64 Cubre la distinción Base64URL que hace tropezar a la gente.
• Validador YAM- porque la mitad de mis fallas de API en el último año fueron 't fallas de API. Fueron un error de sangría de dos espacios en una configuración de CI y el punto final nunca se implementó en absoluto. (Sin embargo, YAML tiene un modo de falla más desagradable que una compilación rota: YAML válido que significa algo que no hiciste & #39; no lo pretendo. Escribí porque version: 1.10 se convierte en 1.1 después de que me costó una implementación.)
• Probador de expresión regular- por el momento necesitas extraer un ID de solicitud de 900 líneas de registro con un patrón que no te confíes.
• Visor de CSV- para el punto final de exportación cuya producción necesita verificar la cordura antes de que alguien la importe a producción.

¿Importa realmente que estos se ejecuten en el navegador?

Sí, y yo diría esto incluso si no hubiera construido el sitio.

Piensa en lo que pegas en una herramienta de depuración. Un JWT, que es un Credencial en vivo hasta que caduque. Una respuesta de API de producción, que son los datos de los clientes: nombres, correos electrónicos, estados de suscripción. Un organismo de webhook, que puede contener un registro de pago. un curl comando con un Authorization cabecera todavía en él.

Ahora considere que una herramienta del lado del servidor, por definición, recibe todo eso. No maliciosamente, solo arquitectónicamente. La pasta entra en una solicitud HTTP, golpea el backend de alguien ' y aterriza en cualquier registro que ejecute. Incluso un operador escrupulosamente honesto termina con su token portador en un registro de acceso que nunca tuvo la intención de mantener.

Las herramientas de Toolz.dev hacen el trabajo en JavaScript en su pestaña. No se carga nada, porque no hay ningún lugar donde cargarlo: el análisis, la decodificación y el hash suceden en su máquina. No lo haces & #39; Tampoco tengo que confiar en mi palabra: abra DevTools, vaya a la pestaña Red, pegue un token y esté atento a una solicitud que nunca llega. Eso & #39; es una auditoría de treinta segundos y debes ejecutarla ninguno Herramienta en la que pegas secretos, la mía incluida. escribí Cómo verificar una herramienta del lado del cliente correctamente Por esta razón exactamente.

Si su organización maneja datos personales de la UE, esto es 't solo higiene: pegar registros de clientes en un servidor de terceros es una actividad de procesamiento, con todo el papeleo del RGPD que eso implica. Las herramientas del lado del cliente eluden la cuestión al no convertirse nunca en un procesador.

un flujo de trabajo que realmente se pega

Seis pasos, en el orden, los ejecuto cuando algo está en llamas:

1. Captura la respuesta cruda. Cuerpo completo, encabezados completos, código de estado. No es su aplicación y la interpretación del mismo es #39;s: los bytes reales. curl -i O la pestaña de la red "Copiar como curl"
2. Formatealo. Formateador JSON. mira el formular Antes de mirar los valores. ¿El campo que necesitas está presente?
3. Decodifica cada cadena opaca. fichas a través de la Decodificador JWT, Blobs base64 a través de la Convertidor Base64, URLs destrozadas a través de la Codificador de URL. Las cuerdas opacas ocultan la respuesta sorprendentemente a menudo.
4. Convierta cada número que podría ser una hora en una fecha. Convertidor de marca de tiempo. Cuente los dígitos primero.
5. diferencia contra una buena respuesta conocida. Diferencia de JSON. Si no tiene una respuesta buena conocida, esta es su señal para comenzar a salvarlos.
6. Solo ahora ve a leer tu código. En este punto, por lo general conoce la línea antes de abrir el archivo.

El orden importa. El paso 6 es donde solía comenzar, y es por eso que ese sábado tomó ocho horas.

Preguntas frecuentes

¿Cuáles son las mejores herramientas gratuitas para depurar las API?

Para la depuración de API diarias, necesita cinco cosas: un formateador y validador JSON, un decodificador JWT, un convertidor de marca de tiempo UNIX, una herramienta de diferencial y un codificador/decodificador de URL. Los cinco son gratuitos en Toolz.dev y se ejecutan completamente en el navegador. Agregue un generador de hash si trabaja con webhooks firmados y un validador YAML si sus despliegues están impulsadas por la configuración.

¿Es seguro pegar una respuesta de JWT o API en una herramienta en línea?

Sólo si la herramienta es del lado del cliente. Un JWT es una credencial activa y una respuesta API suelen ser datos del cliente, por lo que una herramienta del lado del servidor significa enviar ambos a un backend extraño 's. Las herramientas Toolz.dev procesan todo en su navegador con JavaScript y no envían nada a través de la red; verifíquelo usted mismo abriendo DevTools' Pestaña Red mientras pega. Ejecute esa misma verificación en cualquier herramienta que utilice con datos confidenciales.

¿Por qué mi JWT dice "caducado" cuando lo acabo de generar?

La causa más común es un desajuste de unidades. los exp La reclamación es en segundos (RFC 7519 lo define como una fecha numérica), pero JavaScript Date.now() Devuelve milisegundos, por lo que compararlos directamente hace que cada token parezca expirado. Decodificar el token, leer exp, conviértalo en una fecha real con un convertidor de marca de tiempo y verifique si en realidad está en el pasado antes de tocar su código de autenticación.

¿Cómo puedo saber si una marca de tiempo de Unix es en segundos o en milisegundos?

Cuente los dígitos. Diez dígitos son segundos, trece son milisegundos, dieciséis son microsegundos. Si sale una fecha en 1970, le dio a un parser de segundos a un milisegundo; si sale en el año 56122, le dio milisegundos a un segundo analizador. El segundo error es más peligroso porque nada arroja un error.

¿Puedo usar estas herramientas para depurar las API de GraphQL?

Sí. Las respuestas de GraphQL son JSON, por lo que el formateador JSON y el DIFF JSON funcionan sin cambios, y GraphQL normalmente usa la misma autenticación de token portador que decodifica con el decodificador JWT. La única diferencia real es que GraphQL devuelve HTTP 200 con un errors matriz en lugar de un estado que no sea 2xx, así que formatee siempre el cuerpo: la falla está dentro de la carga útil, no en el código de estado.

¿Por qué siempre falla mi verificación de firma de webhook?

Casi siempre porque está haciendo bytes de hash diferentes a los del proveedor. Si su marco analizó el cuerpo JSON y lo volvió a serializar antes de hash, el espacio en blanco o el orden de claves ha cambiado y el HMAC nunca coincidirá. Hash el cuerpo de solicitud sin procesar exactamente como se recibió y verifique si su cliente HTTP agrega una nueva línea.

¿Cuál es la diferencia entre la codificación Base64 y Base64URL?

BASE64 estándar (RFC 4648 §4) Usos + y / En su alfabeto y almohadillas con =. Base64url (RFC 4648 §5) sustituye a los que tienen - y _ Y por lo general deja caer el relleno, por lo que el valor es seguro de poner en una URL o en un JWT. Alimentar los datos de Url de base64 a un decodificador estándar-base64 estricto produce un error o basura, por lo que un decodificador JWT dedicado supera a la decodificación manual de un token.

¿Cómo depurar una respuesta 401 no autorizada?

trabajar hacia afuera desde el token. decodificarlo y comprobar exp en comparación con la hora actual: un token caducado es la causa más común y es invisible hasta que convierta el reclamo a una fecha legible. Si el token está activo, verifique Authorization Encabezado en sí: el esquema debe estar presente y deletreado correctamente (Bearer <token>, un espacio, sin comillas), y un token pegado desde una terminal a menudo lleva una nueva línea que rompe el partido. Después de eso, confirme la aud y iss Las reclamaciones coinciden con lo que espera la API, ya que un token válido emitido para una audiencia diferente se rechaza exactamente como uno malo. Solo entonces comience a sospechar del servidor.

¿Cómo decodificar un JWT sin una biblioteca?

Un JWT consta de tres segmentos base64url unidos por puntos. Divida en los puntos, luego base64url decodifique los dos primeros (el encabezado y la carga útil) y ambos saldrán como JSON simple. El tercer segmento es la firma y no decodifica en nada legible porque son bytes sin formato en lugar de texto. Esto importa más de lo que parece: decodificar un token le indica lo que afirma, no si esas afirmaciones son ciertas. Verificar la firma requiere la clave del emisor 's y pertenece al código de su servidor, nunca a una herramienta del navegador. Lea los tokens aquí para depurar; valídelos en la aplicación.

¿Todavía necesito postman o insomnio si uso estas herramientas?

Sí, resuelven diferentes problemas. Un cliente API envía solicitudes; estas herramientas hacen que las respuestas sean legibles. En la práctica, uso el cliente para activar la solicitud y copiar la salida sin procesar, luego paso a las herramientas del navegador para formatearla, decodificarla, convertirla y diferenciarla. Se sientan uno al lado del otro en el flujo de trabajo en lugar de reemplazarse entre sí.