cURL

Teste o método QUERY direto do terminal. curl aceita -X QUERY nativamente — sem patches, sem builds custom.

---

Requisição básica

curl -X QUERY https://api.exemplo.com/usuarios \
  -d '{"cidade": "São Paulo", "ativo": true}'

---

Headers completos

curl -X QUERY https://api.exemplo.com/usuarios \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"cidade": "São Paulo", "ativo": true, "limit": 25}'

---

Modo verbose (debug)

curl -v -X QUERY https://api.exemplo.com/usuarios \
  -H "Content-Type: application/json" \
  -d '{"cidade": "São Paulo"}'

Saída esperada:

> QUERY /usuarios HTTP/2
> Host: api.exemplo.com
> Content-Type: application/json
> Content-Length: 24
>
< HTTP/2 200
< Content-Type: application/json
< Cache-Control: max-age=60

---

Testando cache (mesma query 2x)

QUERY é cacheable — a segunda requisição idêntica pode vir do cache.

curl -s -o /dev/null -w "HTTP %{http_code} | Tempo: %{time_total}s\n" \
  -X QUERY https://api.exemplo.com/usuarios \
  -H "Content-Type: application/json" \
  -d '{"cidade": "São Paulo"}'

curl -s -o /dev/null -w "HTTP %{http_code} | Tempo: %{time_total}s\n" \
  -X QUERY https://api.exemplo.com/usuarios \
  -H "Content-Type: application/json" \
  -d '{"cidade": "São Paulo"}'

Com Content-Location na resposta, intermediários podem servir a versão em cache.

---

Contra servidor local

# Servidor rodando em localhost:3000
curl -X QUERY http://localhost:3000/api/produtos \
  -H "Content-Type: application/json" \
  -d '{
    "categoria": "eletrônicos",
    "preco_max": 5000,
    "ordenar": "preco_asc"
  }'

Com output formatado:

curl -s -X QUERY http://localhost:3000/api/produtos \
  -H "Content-Type: application/json" \
  -d '{"categoria": "eletrônicos"}' | jq .

---

HTTPie

HTTPie também aceita métodos custom:

# Básico
http QUERY https://api.exemplo.com/usuarios \
  cidade="São Paulo" ativo:=true

http QUERY http://localhost:3000/api/produtos \
  Content-Type:application/json \
  categoria="eletrônicos" preco_max:=5000

http --verbose QUERY https://api.exemplo.com/usuarios \
  cidade="São Paulo"

---

Salvando body em arquivo

Para queries complexas, use um arquivo:

# query.json
cat > query.json << 'EOF'
{
  "filtros": {
    "cidade": "São Paulo",
    "ativo": true,
    "tags": ["premium", "verificado"]
  },
  "paginacao": { "limit": 50, "offset": 0 },
  "campos": ["id", "nome", "email"]
}
EOF

curl -X QUERY https://api.exemplo.com/usuarios \
  -H "Content-Type: application/json" \
  -d @query.json

---

Tabela de flags úteis

Flag	Descrição	Exemplo
-X QUERY	Define o método HTTP	curl -X QUERY url
-d '...'	Envia body (string)	-d '{"key":"val"}'
-d @file	Envia body de arquivo	-d @query.json
-H	Adiciona header	-H "Content-Type: application/json"
-v	Modo verbose	Mostra request/response completos
-s	Modo silencioso	Suprime barra de progresso
-o /dev/null	Descarta body	Útil com -w para métricas
-w	Formato de saída	-w "%{http_code} %{time_total}"
--follow	Segue redirects (novo)	Mantém método QUERY no redirect
-i	Mostra headers da resposta	Útil pra verificar Cache-Control
--json	Atalho Content-Type JSON	curl --json '{}' -X QUERY url

---

Dicas rápidas

# Combinar --json com -X QUERY (curl 7.82+)
curl --json '{"ativo": true}' -X QUERY https://api.exemplo.com/usuarios

curl -s -o /dev/null -w "%{time_total}\n" \
  -X QUERY https://api.exemplo.com/usuarios \
  -d '{"cidade": "São Paulo"}'

curl -X OPTIONS https://api.exemplo.com/usuarios -i

---

Redirects: use --follow, não -L

O curl moderno oferece --follow que respeita a semântica HTTP — se o servidor responde com 303, o redirect usa GET. Com -L, o método original é repetido cegamente em todos os hops.

# Correto
curl --follow -X QUERY https://api.exemplo.com/busca \
  -H "Content-Type: application/json" \
  -d '{"q": "teste"}'

curl -L -X QUERY https://api.exemplo.com/busca  # ⚠️ pode repetir QUERY indevidamente

---

Referências

• QUERY with curl — Daniel Stenberg (autor do curl)
• RFC 10008 — Especificação completa
• curl 8.21.0 release — Versão com suporte completo