Especificação: RFC 10008 — The HTTP QUERY Method
Resumo anotado da especificação completa, com links diretos para cada seção do documento original.
A RFC 10008 define o método QUERY para HTTP — uma requisição segura e idempotente que carrega a consulta no corpo da mensagem (request body) em vez de codificá-la na URI. Diferente do GET, que transmite parâmetros apenas pela query string, e do POST, que não garante segurança nem idempotência, o QUERY combina o melhor dos dois: permite dados complexos no corpo enquanto mantém as propriedades que habilitam cache, retry automático e prefetch pelo navegador. É o primeiro método HTTP novo registrado desde o PATCH (RFC 5789, 2010).
Metadados
Seção intitulada “Metadados”| Campo | Valor |
|---|---|
| Número | RFC 10008 |
| Título | The HTTP QUERY Method |
| Status | Standards Track (Internet Standard) |
| Stream | IETF |
| Publicação | Junho de 2026 |
| Autores | Julian Reschke (greenbytes), James M. Snell (Cloudflare), Mike Bishop (Akamai) |
| Obsoleta | — (nenhuma RFC anterior) |
| Atualiza | — (nenhuma RFC anterior) |
| ISSN | 2070-1721 |
| Link oficial | rfc-editor.org/rfc/rfc10008 |
Seção por seção
Seção intitulada “Seção por seção”Seção 1 — Introduction
Seção intitulada “Seção 1 — Introduction”Apresenta o problema: quando os dados de uma consulta são volumosos demais para a query string, desenvolvedores recorrem ao POST — mas POST não sinaliza segurança nem idempotência. O QUERY resolve esse gap: aceita body, é safe e idempotent, e pode ser cacheado. A seção inclui uma tabela comparativa GET vs. QUERY vs. POST.
Seção 2 — QUERY Method
Seção intitulada “Seção 2 — QUERY Method”Define formalmente o método. O conteúdo da request e seu media type definem a consulta; o origin server determina o escopo com base no target resource. O campo Content-Type é obrigatório — requests sem ele DEVEM ser rejeitadas.
2.1 — Media Types and Content Negotiation
Seção intitulada “2.1 — Media Types and Content Negotiation”Especifica códigos de status para erros de content-type: 400 se ausente ou inconsistente, 415 se não suportado, 422 se a consulta é válida sintaticamente mas não pode ser processada (ex.: tabela SQL inexistente), 406 se o Accept do cliente não é atendido.
2.2 — Equivalent Resource
Seção intitulada “2.2 — Equivalent Resource”Define o conceito de equivalent resource: um recurso hipotético que responderia a GET com o mesmo resultado da requisição QUERY. Servidores podem (mas não precisam) atribuir URIs a esses recursos, tornando-os acessíveis via GET.
2.3 — Content-Location Response Field
Seção intitulada “2.3 — Content-Location Response Field”Uma resposta 2xx pode incluir Content-Location apontando para uma URI onde o resultado pode ser recuperado via GET. O recurso indicado pode ser temporário.
2.4 — Location Response Field
Seção intitulada “2.4 — Location Response Field”O servidor pode atribuir uma URI ao equivalent resource e incluí-la no header Location da resposta 2xx. Um GET futuro nessa URI repete a consulta sem reenviar o body. Se o recurso expirar, o cliente pode refazer a QUERY original.
2.5 — Redirection
Seção intitulada “2.5 — Redirection”Redirecionamentos (301, 302, 307, 308) funcionam como esperado — o cliente reenvia a QUERY para a nova URI. Importante: as exceções de POST→GET nos códigos 301/302 não se aplicam ao QUERY. Um 303 indica que a consulta pode ser satisfeita via GET na URI do Location.
2.6 — Conditional Requests
Seção intitulada “2.6 — Conditional Requests”A selected representation de um QUERY é a mesma de um GET ao equivalent resource. Headers condicionais (If-Modified-Since, If-None-Match) funcionam normalmente, permitindo 304 Not Modified.
2.7 — Caching
Seção intitulada “2.7 — Caching”Respostas a QUERY são cacheáveis. A cache key DEVE incorporar o request content e metadados relacionados. Caches PODEM normalizar o conteúdo (remover encoding, normalizar JSON) para melhorar eficiência — mas apenas para geração da chave, sem alterar a request. O cliente pode usar no-transform para desencorajar normalização.
2.8 — Range Requests
Seção intitulada “2.8 — Range Requests”Range Requests funcionam como em GET, mas têm pouca utilidade prática — formatos de consulta geralmente definem paginação própria (ex.: LIMIT/OFFSET em SQL).
Seção 3 — The Accept-Query Header Field
Seção intitulada “Seção 3 — The Accept-Query Header Field”Define o header de resposta Accept-Query que permite ao recurso anunciar quais media types são aceitos para QUERY. Usa sintaxe de Structured Fields (RFC 9651). O valor se aplica a todas as URIs com o mesmo path (ignora query component).
Seção 4 — Security Considerations
Seção intitulada “Seção 4 — Security Considerations”QUERY pode ser preferível ao GET quando a consulta contém dados sensíveis, pois URIs são mais frequentemente logadas que request bodies. URIs temporárias criadas para resultados não devem expor dados sensíveis da consulta original. Normalização incorreta de cache pode gerar falsos positivos. CORS exige preflight para QUERY (não é CORS-safelisted).
Seção 5 — IANA Considerations
Seção intitulada “Seção 5 — IANA Considerations”Registra o método QUERY e o campo Accept-Query nos registros IANA (detalhes abaixo).
Apêndice A — Examples
Seção intitulada “Apêndice A — Examples”Exemplos detalhados cobrindo: consulta simples, discovery via OPTIONS, discovery de formatos via Accept-Query, uso de Content-Location e Location, respostas indiretas (303), conditional requests, e formatos alternativos (JSONPath, XSLT).
Apêndice B — Selection of the Method Name ‘QUERY’
Seção intitulada “Apêndice B — Selection of the Method Name ‘QUERY’”Explica por que não foi reutilizado SEARCH, REPORT ou PROPFIND: todos vêm do WebDAV, usam application/xml genérico, e “QUERY” captura melhor a relação com o query component da URI.
Definições-chave (verbatim)
Seção intitulada “Definições-chave (verbatim)”“The QUERY method is used to initiate a server-side query. Unlike the GET method, which requests a representation of the resource identified by the target URI, the QUERY method is used to ask the target resource to perform a query operation within the scope of that target resource.”
— RFC 10008, Seção 2
“QUERY requests are safe with regard to the target resource; that is, the client does not request or expect any change to the state of the target resource.”
— RFC 10008, Seção 2
“Furthermore, QUERY requests are idempotent; they can be retried or repeated when needed, for instance, after a connection failure.”
— RFC 10008, Seção 2
“The response to a QUERY method is cacheable; a cache MAY use it to satisfy subsequent QUERY requests.”
— RFC 10008, Seção 2.7
“The cache key for a QUERY request MUST incorporate the request content and related metadata.”
— RFC 10008, Seção 2.7
“Servers MUST fail the request if the Content-Type request field is missing or is inconsistent with the request content.”
— RFC 10008, Seção 2
Registro IANA
Seção intitulada “Registro IANA”Método QUERY
Seção intitulada “Método QUERY”Registrado no HTTP Method Registry:
| Campo | Valor |
|---|---|
| Method Name | QUERY |
| Safe | yes |
| Idempotent | yes |
| Specification | Section 2 of RFC 10008 |
Campo Accept-Query
Seção intitulada “Campo Accept-Query”Registrado no HTTP Field Name Registry:
| Campo | Valor |
|---|---|
| Field Name | Accept-Query |
| Status | permanent |
| Structured Type | List |
| Reference | Section 3 of RFC 10008 |
Comparação: GET vs. QUERY vs. POST
Seção intitulada “Comparação: GET vs. QUERY vs. POST”| Propriedade | GET | QUERY | POST |
|---|---|---|---|
| Safe | sim | sim | potencialmente não |
| Idempotent | sim | sim | potencialmente não |
| URI para a consulta | sim (por definição) | opcional (via Location) | não |
| URI para o resultado | opcional (Content-Location) | opcional (Content-Location) | opcional (Content-Location) |
| Cacheable | sim | sim | apenas para GET/HEAD futuros |
| Body | “sem semântica definida” | esperado | esperado |
RFCs relacionadas
Seção intitulada “RFCs relacionadas”| RFC | Título | Relação com QUERY |
|---|---|---|
| RFC 9110 | HTTP Semantics | Base normativa — define métodos, campos, status codes, content negotiation |
| RFC 9111 | HTTP Caching | Define cache keys e mecanismos que o QUERY estende |
| RFC 9530 | Digest Fields for HTTP | Pode ser usado para validar integridade do request content em QUERY |
| RFC 9651 | Structured Field Values | Sintaxe usada pelo Accept-Query |
| RFC 9535 | JSONPath | Formato de consulta demonstrado nos exemplos |
| RFC 3986 | URI: Generic Syntax | Define o query component — contexto histórico do método |