HTTP QUERY: o que muda para quem usa POST em buscas

Você começa com GET /products?category=laptops. Depois precisa filtrar por várias marcas, combinar condições e enviar intervalos de preço. Representar aquilo num JSON fica mais simples, então é criado o POST /products/search.

Uma escolha razoável. POST pede que o servidor processe o conteúdo recebido conforme as regras daquele recurso. A tabelinha "GET lê, POST cria" ajuda a começar, mas simplifica demais o protocolo. Uma busca cabe perfeitamente na definição de POST.

O QUERY, definido na RFC 10008, publicada em junho de 2026, atende esse caso com um contrato mais específico: enviar uma consulta no body, com semântica segura e idempotente.

Num exemplo simplificado, a mudança fica assim:

- POST /products/search HTTP/1.1
+ QUERY /products/search HTTP/1.1
  Host: api.example.com
  Content-Type: application/json

  {
    "category": "laptops",
    "price": { "max": 5000 },
    "brands": ["dell", "lenovo"],
    "sort": "-rating"
  }

Você vai sentir a diferença quando a conexão falha

Imagine que o servidor recebeu a busca, mas a conexão caiu antes de a resposta chegar. O cliente precisa decidir se tenta de novo.

Com POST, um cliente genérico precisa conhecer o comportamento daquele endpoint para repetir a chamada com segurança. Com QUERY, essa garantia faz parte do método: ele pode reenviar a consulta após uma falha de comunicação, mesmo que a primeira tentativa tenha sido processada.

Aqui, "seguro" significa que a operação não solicita alterações no estado do servidor. Já a idempotência diz que repetir a mesma requisição tem o mesmo efeito solicitado que executá-la uma vez. O preço do notebook pode mudar entre duas buscas e produzir respostas diferentes. Isso não quebra a idempotência.

Por isso, eu revisaria o handler antes de trocar o método no roteador. Se essa "busca" também reserva estoque, existe uma alteração de estado fazendo parte da operação. Chamar aquilo de QUERY seria prometer um comportamento que o código não entrega.

O cache precisa considerar o body

Respostas de QUERY podem ser armazenadas em cache. A chave, porém, precisa incorporar o conteúdo da requisição e os metadados relevantes para interpretá-lo. Duas chamadas para /products/search, uma buscando Dell e outra Lenovo, precisam ser diferenciadas. Usar a mesma URL não torna essas consultas equivalentes, e trocar o método não configura o cache automaticamente.

Mandar esse JSON num GET também não resolve bem: o body de GET não tem semântica geral definida pelo HTTP e pode levar algumas implementações a rejeitar a requisição. Depender desse comportamento exige cuidados com os intermediários no caminho.

E agora o que fazer, usar ou não usar?

Não abriria uma migração de API só para substituir POST por QUERY. Numa busca avançada nova, experimentaria o método e manteria o POST disponível para os consumidores que ainda dependem dele.

Antes de adotar, testaria a requisição passando pelo ambiente de verdade, incluindo o proxy e as regras de segurança. Meu critério seria o funcionamento desse caminho completo, não apenas conseguir registrar uma rota no framework.

No navegador, chamadas entre origens com QUERY exigem preflight de CORS, e a configuração precisa permitir o método. Tem um detalhe nessa comparação: o POST com Content-Type: application/json do exemplo também exige preflight entre origens. Esse custo não é exclusivo do QUERY.

Para filtros que cabem bem na URL, continuaria usando GET. Vejo utilidade no QUERY quando a consulta pede um body e faz sentido comunicar, pelo próprio protocolo, que aquela operação pode ser repetida com segurança. Numa API existente, pesaria isso contra o trabalho de atualizar os consumidores.

Alguém já testou QUERY com o proxy e as regras de segurança de produção no caminho? Queria saber quais adaptações foram necessárias além de registrar a rota.