FAQ — Perguntas frequentes sobre HTTP QUERY

As dúvidas que mais aparecem no Reddit, Hacker News e X — respondidas com base na RFC 10008.

---

QUERY substitui o GET?

Não. QUERY complementa GET. Quando a sua consulta cabe na URL (abaixo de ~8000 octetos), GET continua sendo a melhor opção — simples, universal, cacheable sem nenhum truque. QUERY existe para quando o payload da consulta é grande demais, sensível demais para vazar em logs, ou complexo demais para serializar numa query string. A RFC é explícita: QUERY é um método adicional, não um substituto (RFC 10008, Section 1).

Posso usar QUERY hoje em produção?

Com ressalvas. Node.js 22+ aceita QUERY nativamente, Fastify suporta via addHttpMethod, e .NET 11 Preview já mapeia o método. O risco real são intermediários: proxies, WAFs e CDNs que ainda não reconhecem o método podem rejeitá-lo ou tratá-lo como POST. Para APIs internas onde você controla a infraestrutura, pode usar hoje. Para APIs públicas, mantenha o fallback POST por enquanto.

GraphQL precisa do método QUERY?

QUERY resolve o debate clássico “GET vs POST para GraphQL”. Hoje, GraphQL usa GET para queries cacheáveis (com a query na URL) e POST para mutações — mas queries complexas estouram o limite de URL. Com QUERY, você envia o body (a query GraphQL) com semântica explicitamente safe e idempotent, e caches podem operar normalmente. É exatamente o que faltava.

Como funciona o caching de QUERY?

O response é cacheable, mas a cache key inclui o corpo da request (RFC 10008, Section 2.7). Caches podem normalizar o body — remover encoding, ordenar campos JSON — para evitar misses desnecessários. O servidor pode retornar Content-Location (URI para o resultado) e Location (URI para re-executar a query via GET), permitindo cache convencional depois da primeira request.

Quanto tempo até adoção universal?

O consenso da comunidade aponta 5–10 anos para ubiquidade. A RFC foi publicada em junho de 2026. Node.js já suporta, OpenAPI 3.2 já documenta, mas CDNs, browsers (preflight obrigatório) e frameworks legados precisam de tempo. Para contexto: PATCH (RFC 5789) foi publicado em 2010 e levou anos para se tornar default em frameworks. Use QUERY hoje onde faz sentido, mas não espere suporte universal amanhã.

Por que não usaram o método SEARCH?

O draft original (2015–2021) era chamado SEARCH. A renomeação aconteceu em novembro de 2021. Motivos: SEARCH já existia no registro IANA com semântica WebDAV (RFC 5323), usava XML como formato obrigatório, e carregava bagagem histórica do WebDAV “about which many have mixed feelings” (RFC 10008, Appendix B). QUERY é um nome limpo que reflete a relação com o query component da URI.

O corpo da request é obrigatório?

Não tecnicamente, mas sem body o QUERY é semanticamente idêntico a GET — não faz sentido usar. A RFC exige que Content-Type esteja presente e seja consistente com o conteúdo; servidores MUST rejeitar requests sem Content-Type (RFC 10008, Section 2). Na prática: se não tem body, use GET.

Funciona com HTTP/1.1, HTTP/2 e HTTP/3?

Sim, todos. QUERY é definido na camada semântica do HTTP (RFC 9110), não na camada de transporte. Funciona sobre qualquer versão do protocolo da mesma forma que GET, POST ou qualquer outro método. Nenhuma restrição de versão.

E se o proxy não conhecer QUERY?

A RFC 9110 define que proxies SHOULD encaminhar métodos desconhecidos (Section 9.1). Um proxy pode rejeitar com 501, mas o comportamento correto é forward transparente. O risco prático: proxies/WAFs agressivos (corporativos, CDNs legacy) que mantêm allowlists fechadas de métodos. Teste antes de confiar em intermediários que você não controla.

OpenAPI já suporta QUERY?

OpenAPI 3.2.0 (setembro de 2025) adicionou suporte first-class para operações QUERY. Você pode documentar endpoints QUERY normalmente em specs OpenAPI 3.2+, e ferramentas de geração de código estão começando a emitir clientes com suporte ao método. Swagger UI e outras ferramentas visuais estão em atualização.

QUERY dispara preflight CORS no browser?

Sim, sempre. QUERY não está na lista de métodos CORS-safelisted (GET, HEAD, POST). Toda request cross-origin com QUERY dispara um OPTIONS preflight. A RFC confirma isso explicitamente na Section 4 (Security Considerations). Se latência de preflight é um problema, considere same-origin ou proxy reverso.

QUERY é seguro para retry automático?

Sim. Por definição, QUERY é safe (não altera estado) e idempotent (repetir produz o mesmo resultado). Clients, proxies e load balancers podem retry automaticamente sem risco de efeitos colaterais — ao contrário de POST, onde retry pode duplicar operações. É o principal ganho prático sobre POST /search.