HTTP QUERY: o novo método que tenta resolver a bagunça entre GET e POST

O HTTP ganhou um novo método: QUERY.

E a pergunta natural é: quem liga?

A resposta curta: quem constrói APIs, trabalha com backend, cuida de cache, usa GraphQL, mantém proxies, ou já sofreu tentando enfiar filtros complexos dentro de uma URL gigante.

Ou seja, bastante gente.

Durante anos, o desenvolvimento web viveu um pequeno conflito semântico. Para buscar dados, usamos GET. Só que o GET coloca os filtros na URL. Quando a busca é simples, tudo bem. Quando os filtros viram uma árvore genealógica em JSON, a URL vira um pergaminho medieval.

A alternativa prática sempre foi usar POST para buscar dados. Funciona. Mas semanticamente fica estranho, porque POST costuma indicar processamento, criação ou mudança de estado.

O QUERY chega para ocupar esse espaço: uma requisição de leitura, segura, idempotente e com body.

Em português claro: ele permite mandar filtros complexos no corpo da requisição sem fingir que estamos criando alguma coisa.

O problema do GET: ele funciona até a URL pedir aposentadoria

O GET é o método clássico para leitura.

Quando você faz algo como:

GET /produtos?categoria=notebook&marca=dell&preco_max=5000

está tudo certo. A intenção é clara, a URL é compartilhável, o navegador entende, o cache entende e todo mundo vai dormir feliz.

O problema aparece quando a consulta fica mais complexa:

GET /relatorios?vendedor=123&status[]=ativo&status[]=pendente&data_inicio=2026-01-01&data_fim=2026-06-01&filtros[cliente][cidade]=uberlandia&filtros[cliente][estado]=mg&ordenacao[0][campo]=valor&ordenacao[0][direcao]=desc

E isso ainda é um exemplo bonzinho.

Em APIs reais, filtros podem ter listas, objetos, operadores, agrupamentos, regras de permissão, paginação, ordenação e condições combinadas.

O resultado é uma URL difícil de ler, difícil de debugar e sujeita a limites de tamanho em navegadores, proxies, servidores e middlewares.

Além disso, parâmetros na URL costumam aparecer em logs, histórico, ferramentas de monitoramento e bookmarks. Se o filtro contém informação sensível, isso pode virar problema.

O improviso comum: usar POST para buscar dados

Como o GET não lida bem com consultas complexas no corpo da requisição, muita gente passou a usar POST para busca.

É o caso de muitos endpoints de pesquisa e também de várias APIs GraphQL:

POST /search
Content-Type: application/json

{
  "status": ["ativo", "pendente"],
  "cliente": {
    "estado": "MG",
    "cidade": "Uberlândia"
  },
  "ordenarPor": "valor",
  "direcao": "desc"
}

Tecnicamente, funciona bem.

O body resolve o problema da URL gigante. O payload fica mais organizado. JSON é mais fácil de montar, validar e evoluir.

Mas existe um detalhe: POST não comunica necessariamente uma operação segura e idempotente.

Em termos simples:

Seguro significa que a requisição não deveria alterar o estado do recurso.

Idempotente significa que repetir a mesma requisição várias vezes não deveria causar efeitos diferentes.

O POST pode ser usado para várias coisas. Criar pedido, enviar formulário, disparar processamento, iniciar pagamento, gerar relatório, buscar dados. Ele é flexível até demais.

E quando tudo é POST, a infraestrutura deixa de saber o que pode ser repetido, cacheado ou tratado como leitura.

É tipo chamar tudo de “coisa”. Funciona numa conversa rápida, mas não numa arquitetura séria.

Então o que é o HTTP QUERY?

O QUERY é um método HTTP criado para consultas que precisam de corpo na requisição, mas continuam sendo operações de leitura.

Um exemplo simples:

QUERY /produtos
Content-Type: application/json
Accept: application/json

{
  "categoria": "notebook",
  "precoMaximo": 5000,
  "marcas": ["Dell", "Lenovo"],
  "ordenacao": {
    "campo": "preco",
    "direcao": "asc"
  }
}

A ideia é simples:

GET continua ótimo para buscas simples.

POST continua para operações que processam, criam ou alteram estado.

QUERY entra quando você precisa buscar dados com filtros complexos no body.

O ganho principal é semântico. A requisição diz claramente: “estou consultando, não criando”.

Isso ajuda humanos, bibliotecas, proxies, caches, ferramentas de API e infraestrutura.

Por que o QUERY importa para cache

Um dos pontos mais importantes do QUERY é o cache.

Com GET, caches e CDNs conseguem trabalhar bem porque a URL identifica a consulta.

Com POST, a situação é mais complicada. Como POST pode alterar estado, proxies e caches não devem simplesmente assumir que repetir ou armazenar aquela resposta é seguro.

O QUERY permite uma leitura com body e, ao mesmo tempo, informa que a operação é segura e idempotente.

Mas tem um detalhe importante: o cache não pode olhar só para a URL. Ele também precisa considerar o conteúdo do body e metadados relevantes, como o Content-Type.

Exemplo:

QUERY /relatorios
Content-Type: application/json

{
  "mes": "2026-06",
  "status": "pago"
}

e

QUERY /relatorios
Content-Type: application/json

{
  "mes": "2026-06",
  "status": "pendente"
}

As duas requisições usam o mesmo endpoint, mas têm consultas diferentes.

Se o cache ignorar o body, entrega resposta errada. Aí não é otimização, é sabotagem com cache-control.

O QUERY não mata o GET

Um erro comum seria olhar para o QUERY e pensar: “agora vamos trocar tudo”.

Não precisa.

O GET continua sendo a melhor opção para consultas simples, especialmente quando a URL precisa ser compartilhável, favoritada ou acessada diretamente pelo navegador.

Exemplo:

GET /produtos?categoria=notebook

Isso continua perfeito.

O QUERY faz sentido quando os filtros ficam grandes, estruturados ou difíceis de representar em query string.

Na prática, uma boa regra é:

Use GET para consultas simples e compartilháveis.

Use QUERY para consultas complexas, com filtros estruturados.

Use POST para ações que processam, criam ou alteram estado.

Essa separação deixa a API mais clara e reduz gambiarra semântica. E sim, toda API tem uma gaveta de gambiarra. A meta é não deixar a gaveta virar o armário inteiro.

O impacto para GraphQL

O GraphQL é um dos exemplos mais óbvios.

Hoje, muitas APIs GraphQL usam POST para enviar queries no body:

POST /graphql
Content-Type: application/json

{
  "query": "{ users { id name email } }"
}

Mas, semanticamente, uma query GraphQL geralmente é leitura. Não deveria ser tratada do mesmo jeito que uma mutação.

Com o QUERY, seria possível expressar melhor essa diferença:

QUERY /graphql
Content-Type: application/graphql
Accept: application/json

{
  users {
    id
    name
    email
  }
}

Isso não quer dizer que todo ecossistema GraphQL vai migrar amanhã. Ferramentas, clients, servidores, gateways, CDNs e navegadores precisam evoluir.

Mas a ideia é forte: consultas complexas podem ter body sem precisar se esconder atrás de POST.

O ponto de atenção: suporte ainda vai demorar

Apesar de agora existir como RFC, o QUERY não vira padrão universal de um dia para o outro.

Na prática, algumas ferramentas ainda podem rejeitar métodos HTTP menos comuns. Proxies, firewalls, bibliotecas antigas, gateways de API e clientes HTTP podem precisar de atualização.

Também existe o ponto do CORS. Como QUERY não é um método simples na lista segura do CORS, chamadas cross-origin feitas por navegadores tendem a exigir uma requisição preflight OPTIONS antes.

Isso não inviabiliza o uso, mas precisa ser considerado.

Além disso, para caching funcionar bem, a infraestrutura precisa saber montar a chave de cache considerando o body. Se isso for mal implementado, o cache pode virar fonte de bugs difíceis.

Ou seja: QUERY é promissor, mas não é para sair trocando endpoint em produção no café da tarde.

Como documentar QUERY em APIs

Outro ponto interessante é a documentação.

O OpenAPI 3.2 já contempla operação query no Path Item Object, o que ajuda a descrever APIs que adotarem esse método.

Um exemplo conceitual ficaria assim:

paths:
  /produtos:
    query:
      summary: Consulta produtos com filtros avançados
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                categoria:
                  type: string
                precoMaximo:
                  type: number
                marcas:
                  type: array
                  items:
                    type: string
      responses:
        "200":
          description: Lista de produtos encontrados

Isso é importante porque uma API sem contrato claro vira caça ao tesouro. Só que o tesouro é descobrir por que o frontend quebrou.

Com documentação adequada, ferramentas de teste, geração de cliente e validação podem entender melhor a intenção do endpoint.

Quando vale usar QUERY

O QUERY tende a fazer sentido em cenários como:

• busca avançada com muitos filtros;
• GraphQL queries;
• relatórios com parâmetros complexos;
• consultas com JSONPath, SQL-like ou DSL própria;
• sistemas com cache intermediário;
• APIs públicas que precisam deixar clara a intenção da requisição;
• endpoints em que POST está sendo usado apenas como “GET com body”.

Mas ele não é obrigatório para tudo.

Se uma busca cabe bem na URL, continue com GET.

Se a operação muda algo no servidor, continue com POST, PUT, PATCH ou DELETE, conforme o caso.

QUERY é uma ferramenta nova para um problema específico. E ferramenta boa é aquela que entra onde faz sentido, não onde dá vontade de usar novidade.

O que muda para empresas e times de tecnologia

Para empresas, o impacto do QUERY não é “agora tudo muda”.

O impacto real está em design de APIs.

Times que constroem plataformas, integrações, gateways e APIs públicas ganham uma forma mais correta de representar consultas complexas.

Isso pode melhorar:

clareza semântica, porque leitura deixa de ser fingida como POST;

observabilidade, porque fica mais fácil separar consulta de mutação;

cache, porque intermediários podem tratar a operação como segura;

retries, porque operações idempotentes podem ser repetidas com menor risco;

documentação, porque o contrato da API fica mais expressivo.

O ganho não é glamouroso. É infraestrutura mais limpa. E infraestrutura limpa é igual encanamento bom: ninguém elogia, mas todo mundo sofre quando dá ruim.

Conclusão

O HTTP QUERY resolve um problema antigo: como fazer buscas complexas com body sem abusar do POST e sem transformar a URL em um romance russo.

Ele não substitui o GET. Também não elimina o POST.

Ele apenas coloca cada coisa no seu lugar.

Para consultas simples, GET segue sendo o caminho natural.

Para alterações de estado, POST, PUT, PATCH e DELETE continuam fazendo sentido.

Para consultas complexas, estruturadas e seguras, QUERY finalmente oferece uma semântica própria.

A adoção ainda vai levar tempo. Ferramentas, frameworks, proxies, navegadores e CDNs precisam amadurecer o suporte. Mas o recado já está dado: APIs modernas precisam de mais do que funcionar. Elas precisam comunicar intenção.

E nesse ponto, o QUERY chega bem na hora.