Método HTTP QUERY explicado: RFC 10008, QUERY vs GET vs POST

O método HTTP QUERY é um novo método de requisição, definido na RFC 10008 (junho de 2026), que envia uma consulta no corpo da requisição e é tanto seguro quanto idempotente. Pense nele como um GET com corpo: você obtém o espaço do POST para filtros complexos e as garantias do GET para cache e novas tentativas automáticas.

Experimente o Apidog hoje

Se você já enfiou um filtro de 3 KB em uma URL, ou enviou uma busca somente leitura como POST e viu sua lógica de cache e de novas tentativas ignorá-la, o QUERY é a solução. Este guia aborda o que a especificação diz, como o QUERY se compara ao GET e ao POST, o que já oferece suporte a ele hoje e como testar um endpoint QUERY com seu agente de codificação.

O que é o método HTTP QUERY?

QUERY é um método HTTP que pede ao recurso de destino que execute a consulta descrita no conteúdo da requisição e retorne o resultado. O corpo da requisição e seu Content-Type definem a consulta. O método é seguro (o cliente não espera mudança de estado) e idempotente (repeti-lo tem o mesmo efeito), então clientes, proxies e caches podem repeti-lo e armazená-lo em cache como fazem com o GET.

A especificação é a RFC 10008, "The HTTP QUERY Method", um Proposed Standard publicado em junho de 2026 por Julian Reschke (greenbytes), James M. Snell (Cloudflare) e Mike Bishop (Akamai). A IANA o adicionou ao HTTP Method Registry com "safe: yes, idempotent: yes", bem ao lado do método SEARCH da era WebDAV, do qual ele quase se tornou sucessor.

Uma requisição QUERY se parece com isto:

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json

select=surname,givenname,email&limit=10&match=%22email=*@example.*%22

O servidor responde com 200 OK e o resultado no corpo.

Por que GET e POST não eram suficientes

Você tinha duas opções para uma leitura complexa antes do QUERY, e ambas têm falhas.

O GET coloca tudo na URL. A RFC 10008 lista quatro problemas com isso:

1. Os limites de tamanho são desconhecidos de antemão, porque uma requisição atravessa muitos sistemas. A RFC 9110 apenas recomenda que remetentes e destinatários suportem pelo menos 8.000 octetos.
2. Codificar dados estruturados em uma URI válida é desperdício.
3. As URIs são registradas em logs e adicionadas aos favoritos com muito mais frequência do que os corpos de requisição, o que é um problema de privacidade para filtros sensíveis.
4. Cada combinação de entradas de consulta se torna seu próprio recurso.

GET com corpo também não é a resposta. A RFC 9110 diz que o conteúdo em uma requisição GET não tem semântica definida. Alguns servidores o leem, alguns o descartam, e alguns proxies rejeitam a requisição. Você não pode contar com ele ao longo de todo o caminho.

O POST funciona, mas mente sobre a intenção. Uma busca via POST funciona bem, mas nada informa a um cliente, cache, proxy ou biblioteca de novas tentativas que a operação é somente leitura. Então os caches a ignoram e os clientes não a repetem após uma conexão interrompida. Se você já teve que colar uma chave de idempotência em uma leitura pura só para tornar as novas tentativas seguras, você sentiu isso.

O QUERY mantém o corpo do POST e adiciona as garantias do GET.

QUERY vs GET vs POST

Veja a comparação, com base na Tabela 1 da RFC 10008:

Propriedade	GET	QUERY	POST
Seguro	Sim	Sim	Potencialmente não
Idempotente	Sim	Sim	Potencialmente não
Corpo da requisição	Sem semântica definida	Esperado, define a consulta	Esperado
URI para a própria consulta	Sim, por definição	Opcional, via Location	Não
URI para o resultado	Opcional, via Content-Location	Opcional, via Content-Location	Opcional, via Content-Location
Armazenável em cache	Sim	Sim, o corpo faz parte da chave de cache	Somente para GET ou HEAD posteriores
Preflight CORS dos navegadores	Não para requisições simples	Sempre	Não para requisições simples

Resumindo: use GET quando a consulta couber confortavelmente na URL, QUERY quando não couber, e POST somente quando a requisição alterar o estado. Para relembrar os métodos clássicos, veja nossos guias sobre métodos HTTP e GET vs POST.

O que a RFC 10008 define

O Content-Type é obrigatório

Os servidores DEVEM rejeitar um QUERY cujo Content-Type esteja ausente ou seja inconsistente com o corpo. A RFC recomenda estes códigos de status:

• 400 Bad Request: sem tipo de mídia, ou um tipo que não corresponde ao conteúdo. Os servidores não podem inspecionar o corpo e sobrepor isso.
• 415 Unsupported Media Type: o recurso não suporta esse formato de consulta.
• 422 Unprocessable Content: o formato está correto, mas a consulta não pode ser executada, como um SQL que nomeia uma tabela inexistente.
• 406 Not Acceptable: o cliente pediu um tipo de resposta que o recurso não consegue produzir.

Location e Content-Location

Um servidor pode retornar dois cabeçalhos opcionais que transformam um QUERY em algo que você pode buscar com GET depois:

• Content-Location aponta para o resultado armazenado desta execução específica. Ele pode ser temporário.
• Location aponta para a própria consulta armazenada. Um GET nele reexecuta a consulta com dados atualizados, sem reenviar o corpo.

A RFC sugere que os clientes passem a usar GET na URI de Location para requisições repetidas, já que o cache do GET é mais simples. Se você retornar qualquer um dos cabeçalhos para uma consulta com dados sensíveis, a URI NÃO DEVE conter partes sensíveis do corpo original.

Cache

As respostas de QUERY são armazenáveis em cache. A chave de cache DEVE incluir o conteúdo da requisição e metadados relacionados, como o tipo de mídia. Os caches PODEM normalizar o corpo primeiro, por exemplo removendo a codificação de conteúdo ou normalizando JSON para um tipo +json, para obter mais acertos. A especificação alerta que uma normalização ruim pode retornar a resposta errada, então espere que as CDNs sejam cautelosas aqui.

Redirecionamentos

Um 301, 302, 307 ou 308 significa "envie o mesmo QUERY para a nova URI". Diferentemente do POST, um QUERY não deve ser reescrito como GET em um 301 ou 302. Um 303 See Other significa "busque o resultado com um GET nesta URI".

O cabeçalho Accept-Query

Accept-Query é um novo cabeçalho de resposta que anuncia o suporte a QUERY e os formatos de consulta que um recurso aceita. É uma lista de Structured Field, então faça o parse dela como tal:

Accept-Query: "application/jsonpath", application/sql;charset="UTF-8"

Os clientes também podem descobrir o suporte com OPTIONS e ler o cabeçalho Allow, ou simplesmente enviar o QUERY e tratar um 405 Method Not Allowed.

Quais ferramentas suportam QUERY hoje?

O suporte é irregular, então teste sua própria stack. Aqui está o que confirmamos em 28 de outubro de 2026:

Ferramenta	Resultado
Servidor http do Node.js 24	http.METHODS inclui QUERY; um servidor simples recebeu o método e o corpo
fetch do Node.js 24	Enviou um QUERY com corpo JSON
curl 8.7	curl -X QUERY com -d enviou o método e o corpo
http.client do Python 3.14	Enviou um QUERY com corpo
OpenAPI 3.2	O Path Item Object tem um campo query para operações QUERY
Apidog CLI 2.2.12	O schema de endpoint-create aceita "method": "query"

Aqui está a chamada curl que usamos contra um servidor Node local:

curl -i -X QUERY http://localhost:3000/products \
  -H "Content-Type: application/json" \
  -d '{"q":"running shoe","limit":2}'

O Fetch Standard só proíbe corpo em GET e HEAD, então os navegadores podem enviar QUERY com corpo. O QUERY não é um método safelisted do CORS, porém, então todo QUERY de origem cruzada dispara um preflight. Seu servidor deve listar QUERY em Access-Control-Allow-Methods.

As lacunas estão no meio da rede: proxies reversos, gateways de API, WAFs e CDNs que usam allowlist de métodos ou não incluem o corpo em sua chave de cache. Verifique cada salto antes de publicar. A newsletter APIs You Won't Hate observa que muitos frameworks web já lidam com QUERY diretamente ou por meio de roteamento de métodos personalizados.

Como adotar o QUERY sem quebrar clientes

Você não precisa remover seus endpoints de busca via POST.

1. Adicione o QUERY ao lado da rota POST. Aponte ambos para o mesmo handler. Clientes novos usam QUERY; os antigos continuam funcionando.
2. Anuncie-o. Retorne Accept-Query no recurso e inclua QUERY em Allow nas respostas de OPTIONS e 405.
3. Exija o Content-Type. Retorne 400 ou 415 conforme a RFC recomenda, e 422 para consultas que fazem o parse mas não podem ser executadas.
4. Recorra a 405 ou 501. Os clientes devem reenviar o mesmo corpo como POST quando um salto rejeitar o QUERY.
5. Corrija o CORS. Adicione QUERY a Access-Control-Allow-Methods para clientes de navegador.
6. Decida sobre o cache. Só habilite cache compartilhado onde seu cache usar o corpo como chave. Caso contrário, retorne uma URI de Location e deixe os clientes fazerem GET nela.
7. Documente. No OpenAPI 3.2, defina a operação sob query: no path item:

openapi: 3.2.0
paths:
  /products:
    query:
      summary: Search products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductQuery'
      responses:
        '200':
          description: Matching products

Filtros curtos e simples podem continuar como query strings no GET. A própria RFC 10008 diz que, se sua consulta é tão curta assim, o GET provavelmente é a escolha melhor.

Deixe seu agente de codificação testar um endpoint QUERY com o Apidog CLI

Um novo método significa verificar o caminho feliz, todos os códigos de erro e a rota de fallback. Entregue isso ao Claude Code, Codex ou Cursor e deixe-o comandar o Apidog CLI.

Instale o CLI, faça login e adicione a skill do Apidog ao seu agente:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Depois dê um único prompt ao seu agente:

In Apidog project <projectId>, add a QUERY /products endpoint that takes a
JSON body {q, limit}. Create test cases that assert 200 with an array for a
valid body, 415 for Content-Type text/plain, and 400 with no Content-Type.
Run them against the staging environment and summarize any failures.

O agente lê cada schema, valida seu payload e só então escreve:

apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json

O endpoint.json que ele escreve define "method": "query", que o schema de endpoint-create do CLI lista ao lado de get, post e dos métodos WebDAV. Adicione --upload-report para ver a execução no app Apidog. O mesmo comando apidog run com -r junit entra no CI; veja como executar testes de API no CI com apidog run e como usar o Apidog CLI no Claude Code. O plano Free do Apidog cobre até 4 usuários.

Perguntas frequentes

O método HTTP QUERY é um padrão oficial? Sim. A RFC 10008 é uma RFC da Standards Track, na categoria Proposed Standard, publicada em junho de 2026, e a IANA lista o QUERY no HTTP Method Registry como seguro e idempotente.

O QUERY é apenas um GET com corpo? Quase, mas é melhor definido. A RFC 9110 não dá semântica alguma a um corpo de GET, então os intermediários podem ignorá-lo ou rejeitá-lo. O QUERY faz do corpo a consulta, exige um Content-Type e incorpora o corpo à chave de cache.

Quando devo usar QUERY em vez de POST? Use QUERY para qualquer busca ou filtro somente leitura que seja grande ou sensível demais para uma URL. Mantenha o POST para requisições que criam ou alteram algo.

Os navegadores podem enviar requisições QUERY? Sim, por meio de fetch com um método personalizado. Requisições QUERY de origem cruzada sempre precisam de um preflight CORS, então seu servidor deve permitir o método.

As respostas de QUERY são armazenadas em cache? Podem ser. Os caches devem incluir o corpo da requisição e seus metadados na chave de cache. Muitas CDNs e proxies ainda não fazem isso, então verifique o seu ou retorne uma URI de Location que os clientes possam buscar com GET.

O OpenAPI suporta QUERY? O OpenAPI 3.2 adiciona um campo query ao Path Item Object para operações QUERY, então você pode documentá-las sem extensões.