HTTP ganhou um novo verbo: QUERY. E quem liga?
Durante anos, desenvolvedores lidaram com uma tensão constante ao projetar APIs: como buscar dados de forma eficiente, semântica e performática?
O método GET sempre foi o padrão para consultas. É seguro, idempotente e cacheável por natureza. Mas na prática, quando os filtros se tornam complexos (múltiplas tags, ranges de datas, autores, operadores lógicos AND/OR, etc.), a URL vira um monstro ilegível.
O problema do GET com filtros complexos
GET /api/articles?tags[]=ruby&tags[]=rails&date_from=2026-01-01&author=Edy&sort=-created_at&filter={and:[{or:[...]}]}
Além de feio, esse tipo de URL é difícil de debugar, de documentar e de manter. Proxies e caches às vezes têm limites de tamanho de URL. O resultado? Dor de cabeça.
A solução "funciona, mas..."
Muitos times (inclusive grandes empresas) acabam usando POST para buscas complexas — inclusive o GraphQL adotou essa abordagem.
POST /api/articles/search
Content-Type: application/json
{
"tags": ["ruby", "rails"],
"date_from": "2026-01-01"
}
Funciona tecnicamente. Mas semanticamente é errado. POST é o verbo das mutações. Ele não é cacheável por padrão, a spec não garante idempotência, e caches/proxies/CDNs não podem assumir segurança ao repetir a requisição.
Entra em cena o QUERY
O novo método QUERY resolve exatamente esse problema:
QUERY /api/articles
Content-Type: application/json
{
"tags": ["ruby", "rails"],
"date_from": "2026-01-01"
}
Vantagens:
Semântica correta: você está lendo dados, não criando ou alterando.
Body permitido: filtros complexos ficam no corpo da requisição (JSON, claro e legível).
Safe e cacheável: a especificação define o método como seguro (safe), o que permite que infraestrutura (CDNs, proxies, browsers, servidores) faça cache sem medo.
URLs limpas: adeus URLs gigantescas.
Mas tem um porém...
Como bem apontado, o método QUERY ainda não é um padrão oficial da web. O documento da IETF que o descreve continua sendo um draft. Isso significa:
Suporte em servidores, clientes e bibliotecas ainda é limitado.
Nem todos os proxies e CDNs entendem o verbo QUERY da forma correta hoje.
Em produção, você ainda vai encontrar mais compatibilidade usando GET (com limitações) ou POST.
Ainda assim, o futuro parece promissor. Quando o QUERY for amplamente adotado, vamos poder ter o melhor dos dois mundos: semântica correta + filtros complexos + cacheabilidade.
Quando vale a pena adotar hoje?
Em APIs internas ou em ambientes controlados: sim, vale testar.
Em APIs públicas: ainda é cedo — melhor manter compatibilidade com GET/POST.
Vale acompanhar a evolução do draft da IETF e o suporte em ferramentas como Nginx, Cloudflare, AWS, etc.
O HTTP continua evoluindo. Pequenos verbos como esse podem parecer detalhes, mas melhoram a arquitetura, performance e clareza de sistemas inteiros.
E você, já está usando (ou pretende usar) QUERY nas suas APIs?
Referência visual:
