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
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/
Teste seu conhecimento
Responda às perguntas abaixo para revisar os principais pontos deste artigo.
1. Segundo o artigo, qual é o principal problema de usar o método GET para filtros complexos em uma API?
Resposta correta: B) As URLs ficam gigantes e difíceis de manter
O artigo lista URLs gigantes e filtros complexos difíceis de manter como um dos problemas do GET, apesar de suas vantagens como cache e semântica correta de leitura.
2. Qual é o problema semântico apontado no artigo ao usar POST para realizar buscas/consultas?
Resposta correta: A) POST usa um verbo de escrita para uma operação que na verdade é de leitura
O artigo aponta que usar POST para buscas tem semântica incorreta, pois mistura um verbo de escrita com uma operação de consulta.
3. O que a proposta do método QUERY, discutida na IETF, tenta resolver segundo o artigo?
Resposta correta: B) Permitir consultas complexas com um corpo estruturado, mantendo a semântica correta de leitura
O artigo descreve o QUERY como uma proposta que une body estruturado e semântica de leitura correta, algo que nem GET nem POST resolvem bem sozinhos.
4. Uma equipe está construindo um dashboard analítico com múltiplos filtros complexos, ranges de data e operadores lógicos. Segundo o artigo, o que acontece se essa equipe tentar representar tudo isso via query params na URL com GET?
Resposta correta: B) A URL se torna difícil de ler, debugar e manter
O artigo mostra um exemplo de URL com filtros aninhados via GET e conclui que o resultado é difícil de ler, debugar e manter — exatamente o cenário que o QUERY tenta resolver.