HTTP, status e headers com curl

Status HTTP é a primeira informação de qualquer diagnóstico: 2xx sucesso, 3xx redirecionamento, 4xx erro de quem chamou, 5xx erro de quem serve. A leitura ingênua confunde 401 (não autenticado) com 403 (autenticado, mas sem permissão) e 404 (não existe) com 400 (requisição malformada) — distinções que definem se o problema é do cliente ou do servidor.

curl é o canivete: -I mostra apenas cabeçalhos, -v revela handshake e redirecionamentos, -w extrai tempos por fase (DNS, conexão, TLS, primeiro byte). Medir tempo por fase transforma 'está lento' em 'o TLS handshake leva 800 ms', que é uma frase que se pode corrigir.

Cabeçalhos importam na operação: Host define o virtual host, X-Forwarded-For carrega o IP real do cliente atrás do proxy, Cache-Control decide o comportamento de CDN e Content-Type evita respostas mal interpretadas. Proxy mal configurado que perde esses cabeçalhos gera bugs difíceis de reproduzir.

1. Anatomia de uma requisição

Uma requisição HTTP tem método (GET, POST, PUT, PATCH, DELETE), caminho, headers e, às vezes, corpo. A resposta tem status, headers e corpo. Com curl -v você vê tudo: linhas com > são o que você enviou, com < o que recebeu.

2. Famílias de status

2xx sucesso (200 OK, 201 Created, 204 No Content)
3xx redirecionamento (301 permanente, 302/307 temporário, 304 cache)
4xx erro do cliente (400, 401 sem autenticação, 403 sem permissão, 404, 429 limite)
5xx erro do servidor ou do caminho (500, 502, 503, 504)

Regra de ouro no plantão: 4xx em massa costuma ser deploy de cliente ou mudança de contrato; 5xx é com você.

3. Headers que importam para DevOps

Host: qual site o cliente quer — base de virtual hosts
X-Forwarded-For / X-Forwarded-Proto: IP e protocolo originais quando há proxy
Cache-Control, ETag: comportamento de cache e CDN
Strict-Transport-Security: força HTTPS no navegador
X-Request-Id: correlaciona logs entre serviços

4. Medindo tempo com curl

O -w do curl quebra o tempo em DNS, conexão TCP, handshake TLS, tempo até o primeiro byte e total. Se o TTFB é alto e o resto baixo, o gargalo está na aplicação; se o time_connect é alto, é rede.

5. Health checks bem feitos

Separe liveness (o processo está vivo?) de readiness (pode receber tráfego? banco conectado?). Um /health que consulta tudo pode derrubar o serviço inteiro quando uma dependência secundária oscila.

6. Checagem final

Você deve conseguir ler um curl -v, apontar a fase lenta de uma requisição e explicar 401 vs 403.

Na prática

curl para diagnóstico

bash

curl -I https://api.cloudshop.dev/health
curl -v https://api.cloudshop.dev/health 2>&1 | head -25

curl -s -o /dev/null -w 'dns:%{time_namelookup} conn:%{time_connect} tls:%{time_appconnect} ttfb:%{time_starttransfer} total:%{time_total}\n' \
  https://api.cloudshop.dev/health

curl -X POST https://api.cloudshop.dev/orders \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"productId":"cube-01","qty":2}' -i

curl --resolve api.cloudshop.dev:443:203.0.113.10 https://api.cloudshop.dev/health -I

Nota de segurança: Passe tokens por variável de ambiente, nunca literal no comando: o histórico do shell guarda tudo.

Quebrar o tempo de uma requisição por fase

bash

curl -sS -o /dev/null https://api.cloudshop.dev/health -w '
dns:     %{time_namelookup}s
tcp:     %{time_connect}s
tls:     %{time_appconnect}s
ttfb:    %{time_starttransfer}s
total:   %{time_total}s
status:  %{http_code}
'
# ttfb muito maior que tls => lentidao na aplicacao, nao na rede

Enviar JSON e ver headers

bash

curl -i -X POST https://api.cloudshop.dev/orders \
  -H 'Content-Type: application/json' \
  -H 'X-Request-Id: debug-123' \
  -d '{"sku":"CS-001","qty":1}'
# HTTP/2 201   <- criado
# location: /orders/42

HTTP, status e headers com curl

Objetivos desta aula

1. Anatomia de uma requisição

2. Famílias de status

3. Headers que importam para DevOps

4. Medindo tempo com curl

5. Health checks bem feitos

6. Checagem final

Na prática

Glossário

Conexão com o CloudShop

Quiz da aula

Minhas anotações