Como usar curl para testar APIs rapidamente

1. Introdução ao curl e sua relevância para testes de API

O curl (Client URL) é uma ferramenta de linha de comando que permite transferir dados usando diversos protocolos de rede. Para desenvolvedores que trabalham com APIs, o curl se tornou um aliado indispensável por sua simplicidade e versatilidade. Com ele, é possível fazer requisições HTTP completas sem precisar de interfaces gráficas ou ferramentas pesadas.

Os principais casos de uso do curl em testes de API incluem:
- Testes rápidos de endpoints durante o desenvolvimento
- Depuração de problemas de comunicação entre sistemas
- Automação de testes em scripts e pipelines de CI/CD
- Verificação de cabeçalhos, códigos de status e estruturas de resposta

A instalação é simples na maioria dos sistemas:
- Linux: sudo apt install curl (Debian/Ubuntu) ou sudo yum install curl (CentOS/RHEL)
- macOS: brew install curl ou já vem pré-instalado
- Windows: Baixar do site oficial ou usar winget install curl

2. Estrutura de comandos curl para requisições HTTP

A sintaxe fundamental do curl segue o padrão:

curl [opções] URL

Os métodos HTTP mais comuns são acessados com a flag -X:

curl -X GET https://api.exemplo.com/recursos
curl -X POST https://api.exemplo.com/recursos
curl -X PUT https://api.exemplo.com/recursos/1
curl -X DELETE https://api.exemplo.com/recursos/1

As flags essenciais para testes de API incluem:
- -X ou --request: especifica o método HTTP
- -H ou --header: adiciona cabeçalhos personalizados
- -d ou --data: envia dados no corpo da requisição
- -i ou --include: inclui cabeçalhos da resposta na saída

3. Testando APIs REST com GET e parâmetros

Uma requisição GET simples para um endpoint público demonstra o funcionamento básico:

curl https://jsonplaceholder.typicode.com/posts/1

Para enviar parâmetros de consulta, use a combinação de -G e --data-urlencode para codificar valores especiais:

curl -G "https://api.exemplo.com/usuarios" --data-urlencode "nome=João Silva" --data-urlencode "idade=30"

Para inspecionar cabeçalhos de resposta, utilize -I (apenas cabeçalhos) ou -v (modo verbose completo):

curl -I https://api.github.com
curl -v https://api.github.com

O modo verbose (-v) mostra detalhes como handshake TLS, cabeçalhos enviados e recebidos, e tempo de cada etapa da requisição.

4. Enviando dados com POST, PUT e DELETE

Para criar recursos com POST, envie dados JSON no corpo da requisição:

curl -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{"title":"Teste","body":"Conteúdo do post","userId":1}'

Atualizações com PUT exigem especificar o recurso e enviar os dados completos:

curl -X PUT https://jsonplaceholder.typicode.com/posts/1 \
  -H "Content-Type: application/json" \
  -d '{"id":1,"title":"Atualizado","body":"Novo conteúdo","userId":1}'

Exclusões com DELETE são diretas:

curl -X DELETE https://jsonplaceholder.typicode.com/posts/1

Sempre verifique o código de status retornado: 200/201 para sucesso, 204 para deleção bem-sucedida, 4xx para erros do cliente e 5xx para erros do servidor.

5. Trabalhando com autenticação e cabeçalhos personalizados

Para autenticação básica HTTP, use a flag -u:

curl -u usuario:senha https://api.exemplo.com/protegido

APIs que usam tokens JWT (Bearer) exigem cabeçalho de autorização:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  https://api.exemplo.com/dados

Cabeçalhos customizados ajudam a simular diferentes clientes ou cenários:

curl -H "User-Agent: MeuApp/1.0" \
  -H "Accept-Language: pt-BR" \
  -H "X-Custom-Header: valor-teste" \
  https://api.exemplo.com/recursos

6. Salvando e manipulando respostas

Para salvar a resposta em arquivo, use -o (nome específico) ou -O (nome original do servidor):

curl -o resposta.json https://api.exemplo.com/dados
curl -O https://api.exemplo.com/arquivo.pdf

O modo silencioso -s suprime a barra de progresso e mensagens de erro:

curl -s https://api.exemplo.com/status

Use -w para extrair métricas específicas da requisição:

curl -w "\nCódigo: %{http_code}\nTempo: %{time_total}s\n" \
  -s -o /dev/null https://api.exemplo.com/recursos

Para filtrar dados JSON da resposta, combine curl com jq:

curl -s https://jsonplaceholder.typicode.com/posts | jq '.[] | {id, title}'

7. Testes avançados: cookies, redirecionamentos e timeouts

Para gerenciar sessões com cookies, use -c para salvar e -b para enviar:

curl -c cookies.txt -b cookies.txt \
  -X POST https://api.exemplo.com/login \
  -d "usuario=admin&senha=123"

Para seguir redirecionamentos automaticamente, use -L:

curl -L https://bit.ly/exemplo-link

Configure timeouts para evitar requisições pendentes:

curl --connect-timeout 10 --max-time 30 https://api.exemplo.com/lenta

O --connect-timeout limita o tempo de conexão, enquanto --max-time limita o tempo total da operação.

8. Boas práticas e scripts de automação

Crie scripts shell para testes repetitivos:

#!/bin/bash
URL="https://api.exemplo.com"
TOKEN="seu-token-aqui"

echo "Testando endpoint de usuários..."
curl -s -H "Authorization: Bearer $TOKEN" "$URL/usuarios" | jq '. | length'

echo "Criando novo usuário..."
curl -s -X POST "$URL/usuarios" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"nome":"Maria","email":"maria@teste.com"}'

Combine comandos com && para testes sequenciais:

curl -s -o /dev/null -w "%{http_code}" https://api.exemplo.com/health && \
echo " - API saudável" || echo " - API com problemas"

Use laços para testes em lote:

for id in 1 2 3 4 5; do
  curl -s "https://jsonplaceholder.typicode.com/posts/$id" | jq '.title'
done

Dicas de segurança importantes:
- Nunca hardcode tokens ou senhas em scripts; use variáveis de ambiente
- Armazene credenciais em arquivos com permissões restritas (chmod 600)
- Utilize --insecure apenas em ambientes de desenvolvimento controlados
- Para produção, sempre valide certificados SSL/TLS

O curl é uma ferramenta poderosa que, combinada com boas práticas de scripting, permite criar suites completas de testes de API sem dependências externas complexas.

Referências