HTTP QUERY: o novo método que resolve o limbo entre GET e POST

Por mais de duas décadas, quem constrói APIs convive com o mesmo dilema sempre que uma busca fica complexa demais para caber numa URL: usar GET e estourar limites de tamanho de query string, ou usar POST e abrir mão da semântica segura e cacheável que o GET oferece. A IETF está formalizando a resposta para esse impasse: o método QUERY, definido no draft draft-ietf-httpbis-safe-method-w-body, que já tem implementações experimentais em navegadores e frameworks de servidor.

O problema que motivou o novo método

O GET foi desenhado para recuperar um recurso e carrega duas garantias importantes na especificação HTTP:

• Seguro (safe): não deve causar efeitos colaterais no servidor.
• Idempotente: repetir a mesma requisição várias vezes produz o mesmo resultado.

Essas garantias são o que permite que proxies, CDNs e navegadores cacheiem respostas de GET e façam retry automático sem medo de duplicar uma ação. O problema é que a especificação HTTP/1.1 não define um corpo de requisição para GET de forma confiável — vários servidores, proxies e bibliotecas simplesmente o descartam. Isso força quem precisa enviar filtros complexos, listas grandes de IDs ou estruturas aninhadas (o caso clássico de busca avançada, relatórios ou GraphQL) a recorrer ao POST.

O POST, por sua vez, não é seguro nem idempotente por definição. Um cliente HTTP, um proxy ou o próprio navegador não pode assumir que repetir um POST é inofensivo — por isso ele nunca é cacheado automaticamente e exige cuidado extra em retries.

Resultado prático: times de API acabam usando POST /search ou POST /graphql para operações que são, na essência, leituras. Funciona, mas perde-se cache HTTP padrão, idempotência implícita e a clareza semântica de que aquela chamada não muda estado.

O que o método QUERY propõe

QUERY é um novo método HTTP que combina o melhor dos dois mundos:

• Tem corpo de requisição, como o POST, permitindo enviar payloads estruturados (JSON, XML, o formato que fizer sentido).
• É seguro e idempotente, como o GET — o servidor se compromete a tratá-lo como uma leitura, sem efeitos colaterais.
• É cacheável sob as mesmas regras de cache do HTTP, desde que a resposta inclua os cabeçalhos apropriados (Cache-Control, ETag etc.), já que o corpo da requisição passa a fazer parte da chave de cache.

Na prática, uma chamada de busca complexa passa a se parecer com isto:

QUERY /produtos HTTP/1.1
Host: api.exemplo.com
Content-Type: application/json
Accept: application/json

{
  "filtros": {
    "categoria": ["eletronicos", "informatica"],
    "precoMin": 100,
    "precoMax": 2000
  },
  "ordenarPor": "relevancia",
  "pagina": 1
}

O servidor responde como responderia a um GET: pode anexar cabeçalhos de cache, pode ser servido por um proxy reverso, e o cliente sabe que pode repetir a chamada sem medo de duplicar nada.

Por que isso importa na prática

Busca e filtros avançados. É o caso de uso mais direto: endpoints de busca com múltiplos filtros, listas de IDs ou texto livre extenso deixam de precisar escolher entre URLs gigantescas (GET com query string de centenas de caracteres) ou abrir mão de cache (POST).

APIs tipo GraphQL e relatórios. Consultas que hoje só funcionam via POST — porque o corpo da query não cabe ou não é seguro numa URL — passam a ter um método dedicado que expressa corretamente a intenção "isto é uma leitura".

Cache HTTP nativo. Com QUERY, CDNs e proxies podem, em tese, cachear respostas de buscas complexas sem que a aplicação precise implementar sua própria camada de cache para isso — desde que a infraestrutura suporte o método.

Clareza de intenção. Logs, ferramentas de observabilidade e middlewares de autorização passam a distinguir "isto é uma operação de leitura com payload" de "isto é uma escrita", o que simplifica regras de auditoria e políticas de rate limit diferenciadas para leitura vs. escrita.

O que muda para quem constrói APIs

Adotar QUERY hoje exige atenção a alguns pontos:

• Suporte de infraestrutura ainda é parcial. Navegadores, proxies, load balancers e frameworks HTTP precisam reconhecer o método explicitamente. Onde não houver suporte, a chamada deve cair para POST com um cabeçalho ou convenção que sinalize a semântica de leitura (alguns frameworks já adotam isso como fallback).
• Continua sendo HTTP "comum". QUERY não substitui GET nem POST — é um terceiro método para o caso específico de leitura com payload estruturado. Operações de escrita continuam em POST, PUT, PATCH e DELETE.
• Cache exige disciplina nos cabeçalhos. Como a chave de cache passa a depender do corpo da requisição (e não só da URL), é preciso garantir que Cache-Control, Vary e ETag estejam corretos para evitar respostas cruzadas entre payloads diferentes.
• Ainda é um draft em evolução. Por estar em processo de padronização na IETF, detalhes de comportamento (negociação de conteúdo, interação com Content-Length, comportamento em redirecionamento) podem mudar até a publicação final como RFC.

Onde acompanhar a adoção

Por ser um método novo, a recomendação para times de engenharia é tratar QUERY como uma evolução a observar antes de depender dele em produção: validar o suporte do runtime do servidor, do proxy reverso e dos clientes HTTP usados (navegadores, SDKs, ferramentas internas) antes de migrar endpoints críticos. Para buscas e relatórios complexos que hoje sofrem com URLs gigantes ou POST sem cache, vale já desenhar a API pensando em uma futura migração para QUERY — mantendo o payload de busca bem definido e a operação livre de efeitos colaterais, exatamente como o novo método exige.