Ferramentas de depuração de API: as seis guias que abro quando um terminal se remete a mim

Um ponto de extremidade de ativação de licença em um dos meus projetos Laravel começou a rejeitar todos os tokens que foram entregues. Não alguns tokens. Cada token, incluindo aqueles do mesmo servidor, havia emitido noventa segundos antes. os logs diziam token expired. Os tokens não expiraram. Passei a maior parte de um sábado convencido de que o relógio da caixa havia caído.

não tinha. O bug era uma linha:

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

exp Em um JWT é segundos desde a época - RFC 7519 §4.1.4 é inequívoco sobre isso. Date.now() Em retornos de JavaScript milissegundos. Então, eu estava comparando um número de dez dígitos com um número de treze dígitos e os números de dez dígitos sempre menores. Cada token no universo expirou para sempre. a correção foi Date.now() / 1000. O diagnóstico demorou oito horas porque eu nunca parecia na ficha - continuei relendo meu próprio código, que é o equivalente de depuração de procurar seus óculos enquanto os usava.

O que finalmente quebrou o loop foi colar o token em um decodificador, lendo exp: 1748952000, convertendo isso em uma data e vendo um timestamp duas semanas no futuro. O token estava bom. Minha comparação estava errada. Trinta segundos de observação de dados superam oito horas de olhar para o código.

Isso' s o que este guia é sobre. Não inteligente filosofia de depuração - as ferramentas de navegador específicas, chato, sem glamour EU mantenho em um grupo de tabulação chamado & quot; API Debug, & quot; o que cada um é realmente para, e os modos de falha que eles pegam Tudo aqui é executado cliente-lado sobre Toolz.dev, o que importa mais do que parece quando o que você está prestes a colar é um token de produção.

tl;dr: Quando uma API se comportar mal, pare de ler seu código e comece a ler a carga útil. Formate a resposta com o formatador json. Quebre o token com o decodificador jwt, não uma ferramenta genérica de Base64. mudança de direção exp, iat, e X-RateLimit-Reset em datas reais com o conversor de carimbo de data/hora. Compare uma resposta de trabalho com uma quebrada com a Diferença de texto Ou melhor, o json diff. Decodificar o mutilação da cadeia de consulta com o codificador de url. Tudo isso é executado no seu navegador - o token nunca passa por cima do fio.

Por que a depuração de uma API parece muito pior do que o código de depuração?

Porque você não pode passar por isso. Um bug local tem um rastreamento de pilha, um depurador e um ponto de interrupção. Um bug da API tem uma string. O servidor de outra pessoa produziu essa string, de acordo com regras que você apenas metade sabe, e seu trabalho é trabalhar para trás.

Isso inverte a habilidade usual. O gargalo não é lógica, é legibilidade. Quase todos os bugs de API que eu persegui nos últimos anos eram invisíveis até que eu tornasse os dados legíveis:

• Uma resposta JSON de 4.000 caracteres minificada que acabou por ter "data": null enterrado em profundidade seis.
• Uma carga útil de base64 que decodificou para uma mensagem de erro, a API era muito educada para colocar o código de status.
• Um webhook que falhou na verificação de assinatura porque o corpo tinha uma nova linha à direita que meu cliente HTTP estava adicionando de maneira útil.
• Um carimbo de data/hora que estava em milissegundos quando os documentos disseram segundos. (duas vezes. empresas diferentes.)

Nenhum desses problemas foi difícil. Todos eles foram ilegível Problemas. As ferramentas abaixo existem para tornar os dados legíveis o suficiente para que você perceba o que seus olhos passariam.

Qual ferramenta para qual sintoma?

Esta é a mesa que eu gostaria que alguém tivesse me entreguedo cinco anos atrás. Sintoma à esquerda, primeiro movimento à direita.

Tudo a seguir é a versão longa dessa tabela.

Como faço para tornar uma resposta de API legível em dez segundos?

cole-o no formatador json. Isso e #39; é toda a técnica e I' Não estou sendo simplista - o hábito de depuração de maior alavancagem que tenho é me recusar a fazê-lo Razão sobre Uma carga útil que não formatei.

Aqui está uma forma de resposta que recebo de um provedor de faturamento, exatamente como sai do fio:

{"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}

Formatado, ele' é um objeto totalmente diferente - não para o analisador, mas para mim:

{
  "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
}

agora eu posso ver isso amount é 9900 e não 99.00- it' s em centavos, que é o bug de integração mais comum em pagamentos - e isso current_period_end é um número inteiro de dez dígitos, o que significa segundos, o que significa não entregá-lo a new Date() diretamente.

A validação pega o que seus olhos não vão

A formatação também valida. Uma falha de análise é uma informação. Os erros que realmente aparecem em cargas úteis reais:

• vírgulas à direita. Legal em JavaScript, ilegal em JSON (per RFC 8259). Os acessórios editados à mão estão cheios deles.
• aspas simples. JSON requer aspas duplas. Python str(dict) A saída não é JSON, não importa o quanto pareça.
• Chaves não aspas. A mesma história - isso ' é um objeto JavaScript literal, não JSON.
• NaN / Infinity. Alguns serializadores emitem-nos. JSON não possui literais.
• um nascido. Uma marca de ordem de byte UTF-8 na frente de { Fará com que um analisador restrito rejeite um documento que pareça perfeito na tela.

Se o seu JSON for válido, mas o forma está errado, isso é uma ferramenta diferente do & #39; veja a seção de diferenças abaixo.

Por que usar um decodificador JWT em vez de apenas decodificar o token Base64?

Você pode decodificar um JWT com base em um JWT manualmente. Eu fiz isso por anos. É um mau hábito, e aqui está o porquê.

Um JWT (RFC 7519) são três partes separadas por pontos: cabeçalho, carga útil, assinatura. Cada pedaço é base64url, não o padrão Base64 - RFC 4648 §5, o alfabeto seguro para URL que troca +→- e /→_ e geralmente deixa cair o = preenchimento. Alimente-o a um decodificador estrito padrão-base64 e ele irá dar um erro ou silenciosamente fornecerá bytes de lixo. Portanto, o método manual significa dividir pontos, re-acoplar e trocar o alfabeto, todas as vezes e, em seguida, olhar o JSON bruto.

o decodificador jwt faz tudo isso em uma pasta e - a parte que realmente economiza tempo - apresenta as reivindicações como reivindicações Os que EU verifico, em ordem:

• exp (expiração) e iat (emitido em) - ambos data numérica, ou seja, segundos Desde 1970-01-01 UTC. Este é o campo que comeu meu sábado.
• aud (público) - um token cunhado para sua API de teste será estruturalmente perfeito e ainda rejeitado pelo produto.
• iss (emitente) - após uma migração de provedor de identidade, este é o campo que mudou silenciosamente.
• alg no cabeçalho - se disser none, você tem um problema de segurança, não um problema de depuração.

Veja o exemplo canônico como token que todos viram:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Cabeçalho: {"alg":"HS256","typ":"JWT"}. carga útil: {"sub":"1234567890","name":"John Doe","iat":1516239022}. e iat existe 2018-01-18T01:30:22Z- que você só conhece executando-o através de um conversor de carimbo de data/hora, que é o ponto completo da próxima seção.

O que um decodificador não faz

A decodificação não está verificando. Qualquer um pode decodificar um JWT; a carga útil é codificada, não criptografada. Um decodificador informa qual é o token reivindicações, nunca se a afirmação é verdadeira. A verificação de assinatura acontece no seu servidor com seu segredo, e nenhuma ferramenta de navegador deve ser entregue a esse segredo. Trate um JWT decodificado da maneira que você trataria um envio de formulário: como uma afirmação de um estranho.

Como faço para parar de errar os timestamps?

Aprenda a ler a contagem de dígitos. Esta é a habilidade de depuração mais barata em todo o campo e leva um minuto para aprender.

Dez dígitos significa segundos. Treze significa milissegundos. JavaScript Date Construtor quer milissegundos; UNIX, Python time.time(), GO'S Unix(), php time(), e a maioria das APIs' exp Os campos falam segundos. Tudo a jusante dessa incompatibilidade é o caos.

E o caos é alto em uma direção e silencioso na outra. ração segundos para um analisador de milissegundos e você obtém 1970 - um bug tão óbvio que você o corrige em um minuto. Alimente milissegundos para um segundos analisador e você obtém o ano 56122. eu verifiquei: 1708876200000, interpretado como segundos, pousa em 17 de fevereiro do ano 56122. Essa e no 39; é a direção que envia silenciosamente, porque nada lança - uma assinatura simplesmente nunca expira e ninguém percebe por um quarto.

o conversor de carimbo de data/hora Existe para que você possa resolver isso em uma pasta em vez de discutir sobre isso. cola 1748952000, leia a data, siga em frente. cole o X-RateLimit-Reset Cabeçalho da qual sua API está reclamando e descubra que você tem quatro minutos para esperar, não quatro horas. Se o timestamp for ingenuamente (não Z, sem deslocamento) e você precisa raciocinar sobre o que isso significa em outra região, o conversor de fuso horário é o acompanhamento.

Mais duas armadilhas de carimbo de data/hora que valem a pena saber

O problema de 2038 é real e datado. Um contador de 32 bits assinado transborda em 2147483647, que é 2038-01-19T03:14:07z. Qualquer sistema que ainda armazene tempo em uma entrada assinada de 32 bits - e há mais deles em colunas de banco de dados incorporadas e legadas do que qualquer um deseja admitir - quebra então. Se você e #39; estão definindo expirações de longa duração hoje, você já é capaz de acertar isso.

Os carimbos de data/hora ingênuos são uma mentira por omissão. 2026-02-25T14:30:00 sem rastro Z e não +05:30 Não é um momento no tempo; é um momento em um lugar não especificado. Eu trato qualquer API que devolva os carimbos de data/hora naive como um relatório de bug esperando para ser arquivado. Prefira RFC 3339 (2026-02-25T14:30:00Z), que é o perfil estrito e inequívoco da ISO 8601 que a Web realmente usa.

O que eu faço quando "funcionou ontem"?

Difere. Don' t teorizar - diff it.

Capture a resposta do ambiente de trabalho (ou cave o último bom de seus logs) e a resposta do quebrado e coloque-os lado a lado. Nove em cada dez vezes, há exatamente uma diferença e está olhando para você em cinco segundos.

Para JSON, alcance o json diff antes do diff do texto. Ele analisa os dois lados e compara estrutura0, que significa chaves reordenadas e indentação diferente don & #39; t aparecem como alterações - apenas as reais o fazem Um diff de texto de dois documentos JSON que um servidor serializado em uma ordem de chave diferente acenderá como uma árvore de Natal e não lhe dirá nada.

Para tudo o que é & #39; t JSON - cabeçalhos, corpos brutos, arquivos de configuração, curl saída - use o Diferença de texto. Sua especialidade é a classe de mudança que seus olhos são fisicamente incapazes de pegar: um espaço final, uma guia que se tornou quatro espaços, uma linha CRLF terminando em uma máquina Windows, uma citação encaracolada que um site de documentação substituiu por um direto quando você copiou o exemplo. Eu escrevi um artigo inteiro sobre Por que falhas comparações de texto com olhar, porque me custou uma escalada de suporte uma vez.

Por que meus parâmetros de consulta continuam chegando quebrados?

Como a codificação de url tem três ou quatro sabores sutilmente diferentes e a pilha de todos escolhe um diferente.

Os clássicos, por ordem de que frequência eles me morderam:

• + contra %20. Em uma string de consulta, + Historicamente, significa um espaço (o application/x-www-form-urlencoded convenção). Em um segmento de caminho, + Significa um literal mais. Portanto, uma assinatura base64 contendo +, colocado em uma string de consulta sem codificação, chega com espaços nela e a verificação de assinatura falha. Este é genuinamente desagradável porque o valor ar direito nos logs.
• codificação dupla. %2F torna-se %252F Porque duas camadas de sua pilha a codificaram de maneira útil. O sintoma é um parâmetro que ganha sinais de porcentagem cada vez que passa por um proxy.
• um cru & dentro de um valor. Divide seu parâmetro em dois. agora name=Ben & Jerry é name=Ben Além de um parâmetro de mistério chamado Jerry.

Cole o URL no codificador de url e decodificá-lo. Se decodificá-lo uma vez ainda deixar a porcentagem de fugas para trás, você encontrará sua codificação dupla. Esse é todo o diagnóstico.

Como depurar um webhook que não será verificado?

Este é o que separa "Eu entendo http" de "estive de plantão"

Quase todos os provedores de webhook assinam a carga útil com um HMAC e colocam o resultado em um cabeçalho. Seu trabalho é calcular o mesmo HMAC e comparar. Quando não combina, a assinatura quase nunca é o problema. Os bytes são o problema. Você não está hashing o que eles fizeram.

Os suspeitos de sempre:

1. Você fez um hash do corpo analisado e re-serializado. Sua estrutura analisou o JSON em um objeto, você chamou JSON.stringify() Nele, e agora a ordem das chaves ou o espaço em branco difere por um caractere. você deve fazer o hash do cru Corpo da solicitação, bytes conforme recebido. No expresso, isso significa capturar o buffer bruto antes express.json() chega a isso; em Laravel significa $request->getContent(), não $request->all().
2. Uma nova linha à direita. Alguns clientes anexam um. O provedor não.
3. Você está hashing a string codificada por hexadecimal em vez dos bytes brutos, ou comparando hexadecimal com base64.
4. charset. O corpo tem um caractere de vários bytes e algo ao longo do caminho o transcodificou.

o gerador de haxixe É como eu isolo isso: pegue a corda do corpo exata, faça uma hash, compare com o que meu código produziu para o que ele pensamento era o mesmo corpo. Se esses dois hashes forem diferentes, meu código não está vendo os bytes que acho que está vendo, e o problema nunca foi criptográfico. (Também vale a pena saber: se um provedor ainda oferece assinaturas MD5 ou SHA-1, isso é um sinal sobre a idade de sua plataforma. SHA-256 é o chão agora.)

O que mais vive no grupo de tabulações de depuração?

O elenco de apoio - menos glamoroso, ainda ganha seu lugar:

• gerador de uuid- para uma limpeza X-Request-ID Em todas as chamadas de teste, você pode agredir a informação em três logs de serviços posteriores. Vale a pena saber que os UUIDs obtiveram uma atualização de especificações: RFC 9562 (2024) obsoleto RFC 4122 e padronizado uuidv7, que é ordenado por tempo e, portanto, muito mais gentil com o índice B-Tree do seu banco de dados do que o aleatório V4. Se você estiver escolhendo um esquema de identificação para uma nova mesa hoje, é esse o que você deve ler. existe um Repartição mais longa das versões do UUID Se você quiser.
• conversor de base64- para Authorization: Basic Cabeçalhos (RFC 7617: IT base64(user:password), e sim, que & #39; s codificação, não segurança - TLS é o que protege), e para os blobs binários em linha algumas coisas APIs em campos JSON Base64 custa-lhe ~ 33% de sobrecarga de tamanho, e é por isso que um & quot; inesperadamente grande & quot; carga útil muitas vezes só tem um arquivo nele O Guia completo da base64 Abrange a distinção Base64URL que faz tropeçar nas pessoas.
• Validador YAML- porque metade das minhas falhas de API no último ano foram falhas de API do & #39; t. Eles foram um erro de recuo de dois espaços em uma configuração de CI, e o endpoint nunca foi implantado de forma alguma. (YAML tem um modo de falha mais desagradável do que uma compilação quebrada, embora: YAML válido que significa algo que você fez & #39; t intend. Eu escrevi por que version: 1.10 torna-se 1.1 Depois que me custou uma implantação.)
• testador regex- no momento você precisa extrair um ID de solicitação de 900 linhas de log com um padrão com o qual você e #39; não estou confiante.
• Visualizador de CSV- para o endpoint de exportação cuja produção você precisa verificar a sanidade antes que alguém a importe para a produção.

Realmente importa que eles sejam executados no navegador?

Sim, e eu diria isso mesmo que eu não tivesse construído o site.

Pense no que você cola em uma ferramenta de depuração. Um JWT - que é um credencial ao vivo até que expire. Uma resposta da API de produção, que é dados do cliente: nomes, e-mails, estados de assinatura. Um corpo de webhook, que pode conter um registro de pagamento. um curl comando com um Authorization Cabeçalho ainda nele.

Agora considere que uma ferramenta do lado do servidor, por definição, recebe tudo isso Não maliciosamente - apenas arquitetonicamente A pasta entra em uma solicitação HTTP, atinge o backend de alguém & #39; s e pousa em qualquer registro que eles executam Mesmo um operador escrupulosamente honesto acaba com seu token de portador em um log de acesso que eles nunca pretenderam manter.

As ferramentas no Toolz.dev fazem o trabalho em JavaScript na sua aba Nada é carregado, porque lá' não há para onde carregá-lo - a análise, a decodificação, o hashing acontecem todos na sua máquina Você não & #39; tem que tomar minha palavra para isso, ou: abrir DevTools, ir para a guia Rede, colar um token, e assistir a um pedido que nunca vem That' s uma auditoria de trinta segundos, e você deve executá-lo em qualquer Ferramenta em que você cola segredos, incluídos no meu. eu escrevi Como verificar uma ferramenta do lado do cliente corretamente Por exatamente esse motivo.

Se a sua organização trata dados pessoais da UE, isto é o & #39; t apenas higiene - colar registos de clientes num servidor de terceiros é uma atividade de processamento, com toda a documentação do RGPD que implica As ferramentas do lado do cliente contornam a questão, nunca se tornando um processador.

Um fluxo de trabalho que realmente gruda

Seis passos, na ordem, eu os executei quando algo está pegando fogo:

1. Capture a resposta bruta. Corpo inteiro, cabeçalhos completos, código de status. Não é o seu aplicativo & #39; s interpretação dele - os bytes reais. curl -i ou a guia da rede "Copiar como curl".
2. formate-o. formatador json. olha o forma Antes de você olhar para os valores. O campo que você precisa está presente?
3. Decodifique cada corda opaca. tokens através do decodificador jwt, BLOBs de base64 através do conversor de base64, mutilado URLs por meio do codificador de url. Cordas opacas escondem a resposta com frequência.
4. Transforme todos os números que podem ser um horário em uma data. conversor de carimbo de data/hora. Conte os dígitos primeiro.
5. Diferente de uma resposta conhecida-bem. json diff. Se você não tiver uma resposta conhecida, este é o seu sinal para começar a salvá-los.
6. Só agora vá ler o seu código. A essa altura, você geralmente conhece a linha antes de abrir o arquivo.

A ordem importa. O passo 6 é onde eu costumava começar, e é por isso que aquele sábado levou oito horas.

Perguntas frequentes

Quais são as melhores ferramentas gratuitas para depurar APIs?

Para a depuração de APIs do dia a dia, você precisa de cinco coisas: um formatador e validador JSON, um decodificador JWT, um conversor de carimbo de data/hora Unix, uma ferramenta de diff e um codificador/decodificador de URL. Todos os cinco são gratuitos no Toolz.dev e são executados inteiramente no navegador. Adicione um gerador de hash se você trabalha com webhooks assinados e um validador YAML se suas implantações são orientadas por configurações.

É seguro colar uma resposta JWT ou API em uma ferramenta online?

Somente se a ferramenta for do lado do cliente Uma JWT é uma credencial ao vivo e uma resposta de API geralmente são dados do cliente, portanto, uma ferramenta do lado do servidor significa enviar ambos para um back-end estranho & #39; s. As ferramentas Toolz.dev processam tudo em seu navegador com JavaScript e não enviam nada pela rede - verifique você mesmo abrindo DevTools' Guia de rede enquanto você cola Executar essa mesma verificação em qualquer ferramenta que você usa com dados confidenciais.

Por que meu JWT diz que "expired" quando acabei de gerá-lo?

A causa mais comum é uma incompatibilidade de unidades. o exp A reivindicação está em segundos (RFC 7519 define como um numericdate), mas o JavaScript Date.now() Retorna milissegundos, então compará-los diretamente faz com que cada token pareça expirado. Decodifique o token, leia exp, converta-o em uma data real com um conversor de carimbo de data/hora e verifique se ele está realmente no passado antes de tocar no código de autenticação.

Como posso saber se um timestamp do UNIX está em segundos ou milissegundos?

Conte os dígitos. Dez dígitos são segundos, treze são milissegundos, dezesseis microssegundos. Se uma data for lançada em 1970, você alimentava segundos para um analisador de milissegundos; se ela sair no ano 56122, você alimentava milissegundos para um analisador de segundos. O segundo erro é mais perigoso porque nada gera um erro.

Posso usar essas ferramentas para depurar as APIs do GraphQL?

Sim. As respostas do GraphQL são JSON, portanto, o formatador JSON e o trabalho do diff JSON são inalterados e o GraphQL normalmente usa a mesma autenticação de token de portador que você decodificaria com o decodificador JWT. A única diferença real é que o GraphQL retorna o HTTP 200 com um errors array em vez de um status não-2 xx, então sempre formate o corpo - a falha está dentro da carga útil, não no código de status.

Por que minha verificação de assinatura do webhook sempre falha?

Quase sempre porque você está fazendo feixe de bytes diferente do provedor. Se sua estrutura analisar o corpo JSON e você o re-serializou antes de fazer o hash, o espaço em branco ou ordem de chave mudou e o HMAC nunca corresponderá. Faça o hash do corpo da solicitação bruta exatamente como recebido e verifique se uma nova linha final foi adicionada pelo seu cliente HTTP.

Qual é a diferença entre a codificação base64 e base64url?

Base 64 padrão (RFC 4648 §4) usa + e / Em seu alfabeto e almofadas com =. Base64URL (RFC 4648 §5) substitui aqueles por - e _ E geralmente descarta o preenchimento, então o valor é seguro para colocar em um URL ou JWT. A alimentação dos dados Base64URL para um decodificador básico estrito produz um erro ou lixo, e é por isso que um decodificador JWT dedicado supera a decodificação manual de um token.

Como depurar uma resposta não autorizada 401?

Trabalhe para fora a partir do token. decodificar e verificar exp contra a hora atual - um token expirado é a causa mais comum e fica invisível até que você converta a reivindicação em uma data legível. Se o token estiver ativo, verifique o Authorization Cabeçalho em si: o esquema deve estar presente e escrito corretamente (Bearer <token>, um espaço, sem aspas) e um token colado de um terminal geralmente carrega uma nova linha à direita que interrompe a correspondência. Depois disso, confirme o aud e iss As reivindicações correspondem ao que a API espera, pois um token válido emitido para um público diferente é rejeitado exatamente como um ruim. Só então comece a suspeitar do servidor.

Como decodificar um JWT sem uma biblioteca?

Um JWT são três segmentos base64url unidos por pontos Dividir nos pontos, depois base64url-decodificar os dois primeiros - o cabeçalho e a carga útil - e ambos saem como JSON simples O terceiro segmento é a assinatura, e não decodifica em nada legível porque é bytes brutos em vez de texto Isso importa mais do que parece: decodificar um token diz o que ele afirma, não se essas reivindicações são verdadeiras A verificação da assinatura requer a chave do emissor & #39; e pertence ao seu código de servidor, nunca em uma ferramenta de navegador Leia tokens aqui para depurar; valide-os no aplicativo.

Ainda preciso de Postman ou Insomnia se usar essas ferramentas?

Sim - resolvem problemas diferentes Um cliente API envia solicitações; essas ferramentas tornam as respostas legíveis Na prática EU uso o cliente para disparar a solicitação e copiar a saída bruta, depois movo para as ferramentas do navegador para formatá-la, decodificá-la, convertê-la e diff. Eles sentam-se um ao lado do outro no fluxo de trabalho, em vez de substituir um ao outro.