HTTP QUERY: o método que finalmente fecha a lacuna entre GET e POST

O método HTTP que faltava entre GET e POST: seguro, idempotente, cacheável, com corpo na requisição. Da proposta à padronização pelo IETF.

Quem já construiu uma API de busca conhece esse dilema. Você quer expor um endpoint para consultas complexas: múltiplos filtros, ordenações, uma expressão GraphQL, talvez uma consulta estilo SQL. A primeira ideia é usar GET, que é o método correto do ponto de vista semântico: é seguro, é idempotente, é cacheável. Mas GET não tem um corpo definido, então toda essa complexidade precisa acabar no URI, na forma de query string. Funciona enquanto os parâmetros são poucos. Depois vêm os limites de tamanho (diferentes e imprevisíveis dependendo do cliente, do proxy e da CDN), a codificação de estruturas aninhadas fica ilegível, e dados sensíveis acabam registrados em logs e salvos em favoritos, expostos, na URL.

Então a maioria dos desenvolvedores desiste e usa POST. Funciona: o corpo pode conter qualquer estrutura. Mas POST não é seguro nem idempotente: um intermediário não pode assumir que repetir a requisição é inofensivo, então não há cache automático, não há retentativas seguras, não há otimizações de CDN. É exatamente a escolha que GraphQL, gRPC-over-HTTP, SOAP e XML-RPC fazem há anos: usar POST até para operações somente leitura, pagando o preço em cache e semântica.

Por anos esse foi um compromisso aceito. Em 19 de junho de 2026 deixou de ser: o IETF publicou o RFC 10008, “The HTTP QUERY Method”, como Proposed Standard. Vamos ver de onde vem essa proposta, como ela funciona em detalhe, e o que significa hoje para quem projeta APIs.

O novo método HTTP QUERY abre um caminho entre as duas trilhas percorridas até agora, GET e POST.

De onde vem a proposta

A ideia de um método HTTP seguro com corpo na requisição não é nova: o WebDAV já fazia isso em 2003 com SEARCH (RFC 5323), e antes ainda com PROPFIND e REPORT. O problema desses métodos é que eles carregam toda a bagagem semântica do WebDAV, pensada para um namespace muito específico (gestão de recursos e propriedades), e não se generalizam bem para o resto da web.

A proposta de um método genérico, pensado explicitamente para fechar a lacuna entre GET e POST em todo o HTTP, circula na comunidade do HTTP Working Group há vários anos: as primeiras discussões públicas remontam a pelo menos 2021, quando o draft inicial (que depois se tornou draft-ietf-httpbis-safe-method-w-body) começou a circular entre desenvolvedores. Dali passou por numerosas revisões, catorze versões do draft, discussões na lista de e-mails do HTTPbis Working Group e várias rodadas de Last Call, até chegar, em junho de 2026, à publicação oficial como RFC.

Os autores, três nomes com peso considerável no ecossistema HTTP, são Julian Reschke (greenbytes, historicamente coeditor das especificações HTTP/1.1), James M. Snell (Cloudflare) e Mike Bishop (Akamai). O documento foi patrocinado pelo grupo de trabalho HTTPbis do IETF, com Gorry Fairhurst como Area Director responsável.

Um detalhe que os autores esclarecem explicitamente no documento: o nome escolhido é “QUERY” e não um dos métodos WebDAV existentes (SEARCH, REPORT, PROPFIND), justamente para evitar a ambiguidade semântica desses métodos e capturar melhor a ligação conceitual com o query component de um URI, generalizando o padrão para qualquer tipo de recurso, não só WebDAV.

O problema que ele realmente resolve

O ponto central, que o RFC 10008 deixa claro na introdução, é que nenhum dos dois métodos clássicos cobre bem o caso de consultas somente leitura, mas complexas.

Os limites do GET:

• os limites de tamanho do URI não são claros nem uniformes: variam de cliente para cliente, de proxy para proxy, de CDN para CDN, e ultrapassá-los produz erros difíceis de diagnosticar;
• algumas estruturas de dados são incômodas ou impossíveis de codificar corretamente em um URI (aninhamento profundo, binários, texto livre longo);
• os URIs das requisições acabam mais facilmente registrados em logs, salvos no histórico do navegador ou em favoritos, expondo dados que talvez não devessem aparecer em texto claro em um log.

Os limites do POST:

• não é seguro nem idempotente, então um cliente ou intermediário não pode repetir automaticamente a requisição após um erro de rede sem arriscar efeitos colaterais;
• não é cacheável por padrão, o que complica bastante o trabalho de CDNs e reverse proxies diante de APIs que, de fato, sempre retornam dados somente leitura;
• do ponto de vista semântico é ambíguo: um cliente não consegue deduzir apenas pelo método se um POST cria, modifica, exclui ou simplesmente lê algo.

QUERY pega o corpo do POST e a segurança/idempotência do GET, e continua sendo cacheável: a combinação que, de fato, GraphQL e afins vêm tentando simular há anos usando POST como workaround.

Como funciona na prática

Uma requisição QUERY se parece com uma POST, mas com a garantia explícita de que o servidor não vai alterar o estado do recurso alvo. O Content-Type é obrigatório, porque define o formato em que a consulta é expressa: pode ser JSON, um formato de aplicação como application/graphql, um formato de consulta estruturado como application/jsonpath, ou até texto simples.

Um exemplo com uma consulta GraphQL:

QUERY /api/graphql HTTP/1.1
Content-Type: application/graphql

{ users(role: "admin") { id name email } }

Um exemplo com um filtro de busca estruturado em JSON:

QUERY /feed HTTP/1.1
Content-Type: application/json

{
   "q": "distributed systems",
   "limit": 10,
   "sort": "-published",
   "filters": ["status:active", "type:post"]
}

E um exemplo mais próximo de uma consulta estilo SQL, com resposta em CSV:

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: example/query
Accept: text/csv

select surname, givenname, email limit 10

Se o servidor não entende ou não aceita o Content-Type enviado, responde com códigos de erro precisos: 400 Bad Request se o cabeçalho está faltando ou é inconsistente, 415 Unsupported Media Type se o formato não é suportado, 422 Unprocessable Content se a sintaxe é válida mas a consulta não pode ser processada, 406 Not Acceptable se não consegue produzir uma resposta no formato pedido pelo Accept do cliente.

O cabeçalho Accept-Query

O RFC 10008 também introduz um novo cabeçalho de resposta, Accept-Query, com o qual um recurso declara tanto o suporte ao método QUERY quanto os formatos de consulta que aceita, usando a sintaxe dos Structured Field Values (RFC 9651):

HTTP/1.1 200 OK
Allow: GET, QUERY
Accept-Query: application/json, application/graphql

Cache, condições e redirects

Aqui está boa parte do valor prático do método. A chave de cache de uma resposta QUERY inclui, além do URI alvo, o conteúdo da requisição e os metadados relevantes: duas consultas diferentes no mesmo endpoint produzem entradas de cache distintas, mas consultas idênticas podem ser servidas do cache sem tocar no backend.

QUERY também suporta requisições condicionais, exatamente como GET: um cliente pode enviar If-None-Match com um ETag e receber 304 Not Modified se o resultado não mudou, ou usar If-Modified-Since, If-Match, If-Unmodified-Since e até range requests.

Para vincular a resposta a um recurso concreto e reutilizável, o servidor tem três caminhos:

1. incluir um cabeçalho Content-Location que aponte para um recurso baixável com um GET posterior;
2. incluir um cabeçalho Location para consultas repetíveis no futuro;
3. responder com um redirect 303 See Other para um URI acessível via GET.

E aqui há uma diferença interessante em relação ao comportamento clássico dos redirects: QUERY preserva seu próprio método através dos redirects 301, 302, 307 e 308 (um cliente que segue esses redirects repete uma QUERY, não a transforma em GET). Só o 303 converte explicitamente a requisição seguinte em GET, que é justamente o mecanismo pensado para “materializar” o resultado de uma consulta como recurso autônomo.

Um detalhe a ter em mente para quem trabalha com APIs públicas expostas ao navegador: QUERY não é CORS-safelisted, então requisições cross-origin exigem um preflight OPTIONS, exatamente como já acontece hoje com muitas requisições POST com Content-Type não simples.

Em que ponto está a adoção

Publicar um RFC como Proposed Standard não significa que no dia seguinte todo o ecossistema o suporte. É o primeiro degrau da standards track do IETF: a especificação é estável e está pronta para implementação, mas leva tempo até que navegadores, servidores, proxies, CDNs e bibliotecas cliente a adotem de fato.

No estado atual, nenhum navegador importante implementa QUERY de forma nativa. Do lado do servidor a situação avança mais rápido: o Node.js adicionou suporte ao método em seu módulo http já durante a fase de draft, e o Go, graças ao modo como o net/http é projetado, suporta de fato qualquer método customizado (incluindo QUERY) via http.NewRequest, sem precisar de mudanças na biblioteca padrão. Logo após a publicação do RFC, comunidades de frameworks como Ruby on Rails abriram discussões públicas para avaliar um suporte nativo.

Um caso relevante para quem lê este blog: também o DMVCFramework, o framework REST/MVC de referência para Delphi, já tem um estudo em andamento para avaliar e projetar o suporte ao método QUERY. Se você quiser acompanhar de perto essas decisões técnicas, discuti-las ou propor casos de uso concretos, o lugar certo é o Patreon do DMVCFramework: é lá que compartilho em primeira mão o trabalho sobre essas funcionalidades antes de se tornarem públicas.

O padrão que se espera é o mesmo já visto com outros métodos e cabeçalhos HTTP que se tornaram padrão nos últimos vinte anos: primeiro a adoção do lado do servidor e nas ferramentas de desenvolvimento, depois a consolidação nos frameworks, por fim, mais lentamente, o suporte nativo dos navegadores e das APIs JavaScript como fetch(). Enquanto isso, quem quiser experimentar já pode fazê-lo do lado do servidor: o HTTP, no nível do protocolo de transporte, nunca impediu métodos customizados, então implementar um endpoint que responde a QUERY hoje já é possível na maioria das stacks do lado do servidor, desde que se leve em conta clientes, proxies intermediários e CDNs que talvez ainda não conheçam o método e possam se comportar de forma imprevisível.

O que isso significa para quem projeta APIs

Para quem trabalha hoje em APIs REST ou em endpoints estilo GraphQL, QUERY não é uma urgência, mas é um método a se observar com atenção, porque resolve um problema real e difundido sem introduzir um novo formato ou protocolo, apenas uma peça que faltava no HTTP. Algumas considerações práticas:

• Ainda não é o momento de substituir o tráfego de produção. Com zero navegadores dando suporte nativo, qualquer uso real hoje passa por clientes HTTP customizados ou bibliotecas servidor a servidor, não por um formulário ou um fetch() em um navegador genérico.
• É um candidato natural para endpoints internos ou servidor a servidor. Se você controla tanto o cliente quanto o servidor, por exemplo em uma arquitetura de microsserviços, já pode obter hoje semântica correta e cache em consultas complexas sem esperar pelo suporte dos navegadores.
• Simplifica o design de APIs de busca e de APIs estilo GraphQL. Em vez de forçar POST para operações somente leitura, QUERY finalmente oferece uma forma semanticamente correta de expressar “estou lendo, com uma consulta complexa, e essa requisição é segura de repetir e de colocar em cache”.
• Não é preciso reinventar nada do lado da infraestrutura. Sendo simplesmente um novo método HTTP, toda a infraestrutura existente baseada em cabeçalhos padrão (cache, ETag, redirects, content negotiation) continua funcionando, desde que os vários intermediários no caminho o reconheçam corretamente.
• A conversa entre um cliente Delphi e um servidor DMVCFramework. Um caso bem concreto para quem trabalha com Delphi: uma aplicação desktop (VCL ou FMX), um serviço Windows ou outro servidor, escrito em Delphi ou em qualquer outra linguagem, que precisa consultar um backend DMVCFramework com filtros de busca elaborados (múltiplos campos, intervalos de datas, ordenações, paginação). Hoje a escolha é entre um GET com uma query string incômoda de construir e potencialmente longa demais, ou um POST que abre mão de cache e idempotência só para “encaixar” o filtro no corpo. Com QUERY, esse cliente pode enviar o filtro como corpo estruturado (tipicamente JSON) para o endpoint do DMVCFramework, obtendo semântica correta, retentativas seguras em caso de erro de rede, e a possibilidade real de aproveitar cache e reverse proxies na frente do servidor, algo que com POST hoje não é possível.

Pontos-chave

• A lacuna entre GET e POST agora tem um nome. QUERY combina o corpo do POST com a segurança e a idempotência do GET, e continua sendo cacheável.
• É realidade, não mais só uma proposta. O RFC 10008, “The HTTP QUERY Method”, foi publicado pelo IETF como Proposed Standard em 19 de junho de 2026.
• Não nasce do nada. Inspira-se conceitualmente no SEARCH do WebDAV (RFC 5323, 2003), mas generaliza o padrão para toda a web com um nome novo e sem a bagagem do WebDAV.
• Tem uma sintaxe precisa. Content-Type obrigatório, novo cabeçalho Accept-Query para declarar os formatos suportados, códigos de erro dedicados (400, 415, 422, 406).
• Preserva o cache e a segurança do HTTP. Chave de cache baseada em conteúdo e URI, requisições condicionais, redirects que preservam o método (exceto o 303).
• A adoção está no início. Ainda nenhum navegador nativo, mas Node.js e Go já o suportam do lado do servidor, e frameworks como Ruby on Rails e DMVCFramework (para Delphi) estão avaliando a adoção.

Perguntas frequentes

O que é o método HTTP QUERY?

QUERY é um novo método HTTP, padronizado como RFC 10008, que permite enviar uma requisição com corpo (como POST), mas com semântica segura e idempotente (como GET). O servidor processa o conteúdo da requisição e responde com o resultado, sem alterar o estado do recurso alvo.

Em que ele difere de GET e POST?

GET é seguro e idempotente, mas não tem um corpo definido, então consultas complexas acabam indo para o URI, com limites de tamanho incômodos e codificação difícil. POST aceita corpo, mas não é seguro nem idempotente, portanto não é cacheável e não pode ser repetido automaticamente com segurança. QUERY pega o corpo do POST e a segurança/idempotência do GET, e continua sendo cacheável.

O método QUERY já foi aceito oficialmente?

Sim. Em 19 de junho de 2026 o IETF publicou o RFC 10008, “The HTTP QUERY Method”, como Proposed Standard, o primeiro degrau da standards track do IETF. Os autores são Julian Reschke, James M. Snell e Mike Bishop, produzido pelo grupo de trabalho HTTPbis. O método agora está registrado no IANA HTTP Method Registry como safe e idempotent.

Navegadores e frameworks já suportam QUERY?

O suporte ainda está no início. Nenhum navegador importante o implementa nativamente no momento da publicação do RFC. O Node.js adicionou suporte no lado do servidor em seu módulo http, o Go já o suporta como qualquer método customizado via http.NewRequest, e comunidades como a do Ruby on Rails abriram discussões para adicioná-lo logo após a publicação do RFC. Espera-se uma adoção progressiva nos próximos meses/anos, não imediata.

Por que não reutilizar métodos WebDAV como SEARCH, REPORT ou PROPFIND?

Porque eles carregam toda a bagagem semântica do WebDAV (RFC 5323, RFC 3253, RFC 4918), pensada para um namespace muito específico, e não capturam bem a ligação conceitual com o query component de um URI. Os autores do RFC 10008 escolheram um nome novo, QUERY, justamente para evitar essa ambiguidade e generalizar o padrão para toda a web.

O DMVCFramework vai suportar o método QUERY?

Já está em andamento um estudo para avaliar e projetar o suporte ao método QUERY no DMVCFramework, o framework REST/MVC para Delphi. Quem quiser acompanhar de perto esse trabalho, discutir ou propor casos de uso pode se inscrever no Patreon do DMVCFramework.

Fontes e leituras complementares: IETF, RFC 10008, “The HTTP QUERY Method” (junho de 2026); IETF Datatracker, página de rastreamento do documento; http.dev/query; kmcd.dev, “The HTTP Query Method”; Anton Oko, “HTTP QUERY: A New Method For Search Queries” no Medium; Dan Horovits, “HTTP’s New Method for Data APIs: HTTP QUERY” no Medium; discussão no Hacker News.