curl para APIs: testar cabeçalhos, JSON, tempos e certificados no terminal
Publicado em 2026-10-26 por frfrand
Comandos curl úteis para investigar erros web e HTTP
Quando uma API falha, o navegador costuma mostrar apenas «Network Error». curl permite fazer a mesma solicitação e ver headers, corpo, certificado e tempos sem depender do frontend. É uma faca suíça para distinguir erro de código e erro de infraestrutura.
A ideia é resolver um problema de dados ou implantação que aparece em aplicações reais. Vamos ver o conceito sem rodeios, um exemplo de implementação e o que verificar antes de levá-lo à produção.
O que o curl faz para APIs
curl é um cliente de protocolos que suporta HTTP, HTTPS e muitas opções de depuração. Os headers mostram metadados, o status reflete a resposta do servidor e o modo verbose fornece informações de conexão. Segredo importante: não cole tokens reais em comandos compartilhados ou tickets.
Não basta repetir uma receita se você não entender quem lê os dados, de qual processo e com quais permissões. Em uma aplicação com reservas, faturas ou usuários, uma condição de corrida ou uma política de acesso mal feita pode ser mais grave do que uma API lenta.
Um exemplo concreto
curl -i https://api.ejemplo.com/health
curl -I https://api.ejemplo.com/
curl --fail-with-body -sS https://api.ejemplo.com/health
curl -sS -o /dev/null -w 'status=%{http_code} total=%{time_total}\n' https://api.ejemplo.com/health
# POST de prueba sin credenciales
curl -i -X POST -H 'Content-Type: application/json' -d '{"plazas":2}' https://api.ejemplo.com/demoOs nomes, tabelas e chaves deste exemplo são ilustrativos. Teste primeiro em um banco ou ambiente de ensaio e adapte permissões, índices e versões. Quando houver operações de gravação, não execute consultas de amostra sobre dados de clientes sem revisar o que elas modificam.
Passo a passo
- Verifique GET em uma rota de saúde e anote o status HTTP.
- Use
-ipara ver os cabeçalhos da resposta;-Isolicita HEAD, que nem sempre é suportado. - Meça tempos para distinguir lentidão de conexão e processamento.
- Teste um POST apenas contra um endpoint de teste que não crie cobranças nem pedidos.
- Se falhar TLS, investigue o certificado e o nome em vez de desativar a validação com
-k.
No final, não fique com «o SQL não deu erro». Verifique o efeito real pela API e com testes de concorrência ou permissões, conforme o caso. Em bancos de dados, há erros que só aparecem quando dois usuários fazem algo ao mesmo tempo.
Exemplo de projeto de trabalho
Uma loja envia dados JSON, mas a API espera outro nome de campo. Com curl, você recebe 422 ou 400 e um corpo que explica a validação, sem se perder investigando o proxy.
Esse cenário ajuda a distinguir desempenho de consistência. Acelerar uma consulta não serve se permitir criar duas reservas para uma única vaga, nem um banco enorme resolve o fato de o backend permitir consultar dados de outro cliente.
O erro típico
curl -I envia HEAD e pode retornar um erro diferente de GET; para verificar uma API que oferece apenas GET, use GET. Não publique comandos com tokens bearer reais.
Também convém ter um plano de recuperação. Antes de alterar esquema, usuários ou políticas, faça uma cópia verificável ou migração reversível e verifique se o aplicativo pode continuar funcionando durante a mudança.
Como resolveria com o ArduMaker?
Se o seu backend está no ArduMaker, compare a resposta do curl com os logs do FastAPI, Django e Nginx no VPS. É um diagnóstico mais preciso do que reiniciar servidores.
O ArduMaker permite implantar serviços a partir do Git e trabalhar com bancos de dados e processos dentro do VPS. O painel não substitui a lógica da sua aplicação: transações, permissões e validações devem estar corretamente projetadas no código e no banco de dados.
Três verificações antes de publicar
Integridade: se uma solicitação for repetida ou falhar no meio do caminho, os dados terminam em um estado válido?
Segurança: um usuário autenticado pode acessar apenas suas informações, e a API utiliza uma identidade de banco de dados com permissões mínimas?
Recuperação: você sabe restaurar os dados e reverter a versão de código compatível se uma atualização der errado?
Se você puder responder a essas três perguntas com testes, seu backend estará bastante mais preparado do que quando você apenas verificou se o endpoint retornava 200.
Recursos para aprofundar
Para encerrar: escolha a solução mais simples que permita manter dados corretos, seguros e recuperáveis. O desempenho vem depois de medir.