HTTP QUERY Method: quando GET e POST não resolvem tão bem

Filtros simples funcionam bem com GET. Filtros complexos viram um caos. Entenda a proposta do método QUERY para resolver esse impasse sem abrir mão da semântica HTTP.

29/08/2026 Desenvolvimento

Comparação entre os métodos HTTP GET, POST e QUERY

No design de APIs, existe um problema clássico: filtros simples funcionam perfeitamente com GET, mas filtros complexos acabam virando um caos.

Foi justamente daí que surgiu a proposta do método QUERY, hoje em discussão na IETF.

Três abordagens diferentes

1. GET

Responsável por consultas tradicionais usando query params na URL.

Vantagens: simples, cacheável, semântica correta para leitura.

Problemas: URLs gigantes, filtros complexos difíceis de manter, limite de tamanho em alguns clients e proxies.

GET /api/articles?tags[]=ruby&tags[]=rails&date_from=2026-01-01

2. POST

Muita gente usa POST para buscas complexas com body JSON.

Vantagens: payload estruturado, fácil de expandir, funciona bem tecnicamente.

Problemas: semântica incorreta — usa um verbo de escrita para uma operação de leitura —, nem sempre cacheável, mistura comando com consulta.

POST /api/articles/search
{
  "tags": ["ruby", "rails"],
  "date_from": "2026-01-01"
}

3. QUERY

Proposta da IETF para permitir consultas complexas mantendo semântica de leitura.

Vantagens: body estruturado, semântica correta, melhor suporte conceitual para cache.

Desafios: ainda é draft, pouco suporte no ecossistema, ferramentas ainda não tratam como padrão.

QUERY /api/articles
{
  "tags": ["ruby", "rails"],
  "date_from": "2026-01-01"
}

Fluxo de decisão

Consultas simples → use GET
Filtros complexos hoje → muitas equipes usam POST
Futuro possível → QUERY pode virar alternativa oficial

Um exemplo prático

Imagine um dashboard analítico com múltiplos filtros, paginação, ranges de data, ordenação e operadores lógicos complexos.

Com GET, a URL pode virar isso:

/api/articles?filter={and:[{or:[...]}]}

Resultado: difícil de ler, difícil de debugar, difícil de manter.

É exatamente esse cenário que o QUERY tenta resolver.

Vantagens do QUERY

Semântica de leitura
Payload limpo
Melhor organização
Consultas complexas mais legíveis
Potencial de cache

Desafios do QUERY

Ainda não é padrão oficial
Suporte limitado em gateways e CDNs
Ferramentas HTTP ainda não adotaram amplamente
Pode gerar incompatibilidade entre clients e servidores

O ponto mais importante

Em backend, "funcionar" não significa "ser o melhor design".

Arquitetura de API envolve semântica HTTP, interoperabilidade, cache, compatibilidade e evolução do protocolo.

E é por isso que discussões como essa são tão interessantes: porque APIs não são só endpoints. São contratos.

E você?
Usaria QUERY em produção hoje?

Saiba mais:
Draft do método QUERY na IETF: https://datatracker.ietf.org/doc/draft-ietf-httpbis-safe-method-w-body/