Guia de Testes e Depuração de API: Do cURL às Ferramentas Online

Ferramentas de desenvolvimento

Métodos de Requisição HTTP

Método Uso Idempotente Seguro
GET Obter recurso ✅ ✅
POST Criar recurso ❌ ❌
PUT Atualização completa ✅ ❌
PATCH Atualização parcial ❌ ❌
DELETE Excluir recurso ✅ ❌
HEAD Obter cabeçalhos ✅ ✅
OPTIONS Preflight CORS ✅ ✅

Cabeçalhos de Requisição Comuns

Cabeçalho Descrição Exemplo
Content-Type Formato do corpo application/json
Accept Formato de resposta esperado application/json
Authorization Informação de autenticação Bearer token...
User-Agent Identificação do cliente Mozilla/5.0...
Cookie Cookie session=abc123
X-Request-ID ID de rastreamento da requisição UUID

Valores Comuns de Content-Type

Valor Uso
application/json Dados JSON
application/x-www-form-urlencoded Dados de formulário
multipart/form-data Upload de arquivos
text/plain Texto puro
text/html HTML

Métodos de Autenticação

1. Bearer Token (mais usado)

# cURL
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  https://api.example.com/users

# JavaScript
fetch('https://api.example.com/users', {
  headers: {
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiJ9...',
  },
});

2. Basic Auth

# cURL (codificação automática)
curl -u username:password https://api.example.com/users

# Codificação manual
# Base64("username:password") = "dXNlcm5hbWU6cGFzc3dvcmQ="
curl -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  https://api.example.com/users

3. API Key

# Método 1: Header
curl -H "X-API-Key: your-api-key" \
  https://api.example.com/users

# Método 2: Parâmetro de consulta
curl "https://api.example.com/users?api_key=your-api-key"

Detalhes do Comando cURL

Requisição GET Básica

# GET mais simples
curl https://api.example.com/users

# Mostrar cabeçalhos de resposta
curl -i https://api.example.com/users

# Mostrar apenas cabeçalhos de resposta
curl -I https://api.example.com/users

# Seguir redirecionamentos
curl -L https://example.com/redirect

Requisição POST

# Dados JSON
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

# Dados de formulário
curl -X POST https://api.example.com/users \
  -d "name=Alice&email=alice@example.com"

# Upload de arquivo
curl -X POST https://api.example.com/upload \
  -F "file=@photo.jpg" \
  -F "description=My photo"

Opções Avançadas

# Configuração de timeout
curl --connect-timeout 5 --max-time 30 https://api.example.com

# Salvar em arquivo
curl -o response.json https://api.example.com/users

# Modo silencioso (sem barra de progresso)
curl -s https://api.example.com/users

# Saída detalhada (para depuração)
curl -v https://api.example.com/users

# Ignorar verificação de certificado SSL (apenas ambiente de desenvolvimento)
curl -k https://self-signed.example.com

# Proxy
curl -x http://proxy:8080 https://api.example.com

# Cookie
curl -b "session=abc123" https://api.example.com/users

# Salvar e enviar Cookie
curl -c cookies.txt -b cookies.txt https://api.example.com/users

Códigos de Status HTTP Comuns

Código Significado Causa Comum
200 OK Sucesso
201 Created POST criado com sucesso
204 No Content DELETE com sucesso
301 Moved Permanently Redirecionamento permanente
304 Not Modified Cache acertado
400 Bad Request Parâmetros incorretos
401 Unauthorized Não autenticado
403 Forbidden Sem permissão
404 Not Found Recurso não existe
409 Conflict Conflito de recurso
422 Unprocessable Entity Validação falhou
429 Too Many Requests Limitação de taxa
500 Internal Server Error Erro do servidor
502 Bad Gateway Serviço upstream indisponível
503 Service Unavailable Serviço sobrecarregado

Usar ToolsKu para Testar API

Converter cURL para Código

  1. Abrir Ferramenta cURL para Código
  2. Colar o comando cURL
  3. Selecionar a linguagem destino (JavaScript/Python/Go/Java, etc.)
  4. Copiar o código gerado

Exemplo

# Entrada cURL
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token123" \
  -d '{"name": "Alice"}'

Convertido para JavaScript:

const response = await fetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer token123',
  },
  body: JSON.stringify({ name: 'Alice' }),
});
const data = await response.json();

Técnicas de Depuração de API

1. Ver Requisição/Resposta Completa

# -v mostra informações detalhadas
curl -v https://api.example.com/users

# Saída:
> GET /users HTTP/1.1          ← Linha de requisição
> Host: api.example.com        ← Cabeçalho de requisição
> Authorization: Bearer ...
>
< HTTP/1.1 200 OK              ← Linha de resposta
< Content-Type: application/json ← Cabeçalho de resposta
< X-RateLimit-Remaining: 99
<
[{"id": 1, "name": "Alice"}]   ← Corpo da resposta

2. Formatar Resposta JSON

# Usar jq para formatar
curl -s https://api.example.com/users | jq

# Usar python
curl -s https://api.example.com/users | python -m json.tool

# Ou usar a ferramenta de formatação JSON do ToolsKu

3. Medir Tempo de Resposta

# Estatísticas detalhadas de tempo
curl -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" \
  -o /dev/null -s https://api.example.com/users

# Saída:
# DNS: 0.012s
# Connect: 0.035s
# TTFB: 0.120s
# Total: 0.125s

4. Solucionar Problemas de CORS

Erro do navegador:
Access to fetch at 'https://api.example.com' from origin 'https://app.example.com'
has been blocked by CORS policy

Passos para solucionar:
1. Verificar requisição preflight OPTIONS
   curl -X OPTIONS -H "Origin: https://app.example.com" \
     -H "Access-Control-Request-Method: POST" \
     -i https://api.example.com/users

2. Verificar cabeçalhos de resposta
   Access-Control-Allow-Origin: https://app.example.com
   Access-Control-Allow-Methods: GET, POST, PUT, DELETE
   Access-Control-Allow-Headers: Content-Type, Authorization
   Access-Control-Max-Age: 86400

5. Solucionar Problemas de Autenticação

Solução de 401 Unauthorized:
1. O Token expirou? → Usar ferramenta de decodificação JWT para verificar exp
2. O formato do Token está correto? → Verificar prefixo Bearer
3. O Token foi enviado? → curl -v verificar cabeçalhos de requisição

Solução de 403 Forbidden:
1. O usuário tem permissão? → Verificar função do usuário
2. O IP está na lista de permissão? → Verificar logs do servidor
3. Excedeu o limite de frequência? → Verificar código de status 429

Melhores Práticas de Testes de API

1. Gestão de Variáveis de Ambiente

# Usar variáveis de ambiente para armazenar informações sensíveis
export API_BASE="https://api.example.com"
export API_TOKEN="your-token"

curl -H "Authorization: Bearer $API_TOKEN" "$API_BASE/users"

2. Coleção de Requisições

#!/bin/bash
# api-test.sh

BASE="https://api.example.com"
TOKEN="Bearer $API_TOKEN"
HEADER="-H 'Content-Type: application/json' -H 'Authorization: $TOKEN'"

# Obter lista de usuários
get_users() { curl -s $HEADER "$BASE/users" | jq; }

# Criar usuário
create_user() { curl -s -X POST $HEADER -d "$1" "$BASE/users" | jq; }

# Obter um usuário
get_user() { curl -s $HEADER "$BASE/users/$1" | jq; }

# Uso
get_users
create_user '{"name":"Bob"}'
get_user 1

3. Testes Automatizados

// Escrever testes de API com fetch
async function testApi() {
  // Testar GET
  const listRes = await fetch('/api/users');
  console.assert(listRes.status === 200, 'GET /users should return 200');

  // Testar POST
  const createRes = await fetch('/api/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: 'Test' }),
  });
  console.assert(createRes.status === 201, 'POST /users should return 201');

  const created = await createRes.json();
  console.assert(created.name === 'Test', 'Name should match');
}

Perguntas Frequentes

Problemas com aspas do cURL no Windows?

O CMD do Windows usa aspas duplas, o PowerShell tem problemas de escape:

# No PowerShell, cURL é um alias de Invoke-WebRequest
# Usar curl.exe para invocar o cURL real
curl.exe -X POST https://api.example.com/users `
  -H "Content-Type: application/json" `
  -d '{\"name\": \"Alice\"}'

Como solucionar timeout?

1. DNS lento? → curl -w verificar time_namelookup
2. Conexão lenta? → curl -w verificar time_connect
3. Processamento do servidor lento? → curl -w verificar time_starttransfer - time_connect
4. Transmissão de resposta lenta? → curl -w verificar time_total - time_starttransfer

Resumo

A depuração de API é parte do dia a dia do desenvolvedor: dominar os comandos cURL, os códigos de status HTTP, os métodos de autenticação e as técnicas de depuração permite localizar rapidamente problemas de interface. A Ferramenta cURL para Código e a Ferramenta de Formatação JSON do ToolsKu são ótimas companheiras para depuração de API, ajudando você a testar interfaces e revisar respostas rapidamente.

#API testing#HTTP requests#cURL#API debugging#tutorial