O HTTP QUERY chegou. Você deve reescrever seus endpoints de busca?

Você provavelmente entrega “busca” como um POST para /search com um corpo JSON porque seus filtros não cabem em uma URL. Funciona — mas você abriu mão da cacheabilidade, embaralhou a observabilidade e ensinou cada cliente um formato de payload sob medida. O novo método HTTP QUERY quer consertar isso: uma requisição segura e idempotente que permite corpo como POST, mas não pretende alterar estado, como GET. O debate voltou à capa nesta semana, com novas explicações e threads acaloradas. Vamos pular o bikeshedding e decidir: você deve adotar QUERY em 2026?

O que o QUERY muda — e por que você deve se importar

Hoje você tem três escolhas ruins para leituras complexas:

• GET com uma URL longa demais e codificação desconfortável de filtros estruturados (arriscando limites de proxy e dores de cabeça com assinaturas).
• POST que semanticamente “lê”, o que quebra o cache padrão, induz WAFs a erro e confunde analytics.
• Criar seu próprio RPC sobre POST e torcer para que você no futuro lembre das regras.

QUERY propõe um quarto caminho: tratar leituras complexas como operações seguras e idempotentes com um corpo na requisição. Isso parece entediante. Não é. É uma chance de recuperar performance, reduzir contas de cloud e simplificar a semântica da sua API.

Os benefícios práticos, quantificados

• Ganhos de CDN e cache na borda: apps com muita busca costumam ter 30–60% das requisições indo para endpoints de leitura. Mesmo uma taxa conservadora de acertos de cache na borda de 20–30% em QUERY pode cortar 30–80 ms da latência p95 e reduzir 10–25% de CPU na origem para workloads de listagem/busca.
• WAF e observabilidade mais limpos: Seguro + idempotente implica tratamento padrão diferente. Você ganha dashboards mais claros, limites de taxa mais simples e menos tempo ajustando regras para permitir POSTs inofensivos.
• Melhor ergonomia para clientes: Chega de ginástica com URL. Agentes e SDKs podem enviar filtros estruturados sem re‑encodar JSON em query strings.

Mas há armadilhas. Middleboxes, navegadores, SDKs e especificações foram construídos em torno de GET/POST. QUERY é novo, o que significa arestas cortantes. Vamos mapeá-las.

Um framework de decisão de CTO para adotar QUERY

1) Qual é o seu perfil real de problemas?

• Se seu tráfego de leitura é dominado por listas e facetas de baixa cardinalidade e altamente cacheáveis (pense: navegação de catálogo, feeds top‑N), QUERY oferece ROI real.
• Se suas leituras são profundamente personalizadas e com baixo reúso (ex.: dashboards por usuário, estado efêmero de agentes de IA), os ganhos de cache serão limitados; não espere milagres.
• Se você está brigando com limites de tamanho de URL via proxies ou dores de cabeça de assinatura em GET, o corpo do QUERY resolve isso de forma limpa.

2) Seu caminho de rede suporta um método novo?

Muita infraestrutura descarta ou trata mal verbos desconhecidos por padrão. Antes de se comprometer, rode um teste de pass-through do método em cada salto:

• SDKs de cliente e stacks mobile: Verifique se aceitam métodos arbitrários e não convertem silenciosamente para POST. Navegadores modernos e fetch permitem métodos não padronizados, mas disparam preflight de CORS em chamadas cross-origin.
• Borda/CDN: Cloudflare, Akamai e Fastly passam métodos desconhecidos; cacheá-los é um passo separado e explícito de configuração.
• Balanceadores de carga e API gateways: AWS ALB/NLB, API Gateway, GCP Load Balancers, NGINX, Envoy e HAProxy passam métodos arbitrários, mas conjuntos de regras de WAF podem bloquear por padrão. Teste com um endpoint sintético que ecoa :method.
• Service mesh: Envoy/Istio suportam métodos customizados, mas verifique os matchers de rota, RBAC e filtros de autorização que podem enumerar verbos.

Configure um canário de 48 horas que envie QUERY para uma rota no‑op ao longo de todo o caminho de produção e monitore:

• 4xx/5xx por salto (borda, LB, gateway, serviço)
• Remapeamentos inesperados de método (substituição POST/GET)
• Bloqueios do WAF e desafios de proteção contra bots

3) Você precisa de suporte em navegador — ou é servidor‑a‑servidor?

Se seu front-end chamará QUERY a partir do navegador, aceite o custo de CORS e do preflight. Métodos não simples disparam uma requisição OPTIONS em toda chamada cross-origin, a menos que esteja em cache. Em UIs de alta rotatividade, esse ruído aparece.

• Mitigação: co‑aloque sua API sob o mesmo eTLD+1 do seu app para evitar CORS totalmente, ou faça cache agressivo do preflight com Access-Control-Max-Age (ex.: 600–3600 segundos onde for seguro).
• Se não puder evitar cross‑origin, meça a taxa de preflight; em muitas SPAs, 30–50% das primeiras leituras por rota incorrerão em preflight sem tuning.

4) Sua estratégia de cache e chave faz sentido para QUERY?

Caches identificam entradas por método + URL (+ às vezes cabeçalhos/corpo). Com QUERY, o corpo da requisição passa a participar da identidade do cache. Isso é poderoso — e perigoso.

• Canonicalizar corpos de requisição: Ordene chaves JSON e elimine vazios/nulls para que filtros semanticamente idênticos colidam no cache em vez de se fragmentarem.
• Limite a cardinalidade: Adicione normalização imposta pelo servidor (ex.: travar o page size em 100, facets top‑N) para evitar explosões de “chaves de cache não limitadas”.
• Negociação de conteúdo: Se seu endpoint pode retornar múltiplas representações, garanta que Vary esteja no tamanho certo; não inclua acidentalmente cabeçalhos amplos que destruam sua taxa de acerto.
• Configuração de CDN: A maioria das CDNs não faz cache de não‑GET por padrão. Você precisará de regras explícitas ou lógica programável na borda para cachear QUERY. Comece com um TTL pequeno (ex.: 10–60s) e aumente gradualmente.

5) Sua descrição de API, codegen e clientes vão acompanhar?

OpenAPI 3.1 enumera métodos e ainda não inclui QUERY. Muitos geradores assumem apenas os verbos padrão.

• Gambiarra de curto prazo: Documente endpoints QUERY como POST no OpenAPI com uma extensão x-http-method e implemente o QUERY real no gateway. Gere clientes a partir de POST; troque para QUERY por baixo dos panos primeiro nos caminhos S2S.
• Considere dupla exposição: Ofereça POST e QUERY temporariamente. Use POST para clientes de navegador se o atrito de CORS for alto; roteie servidor‑a‑servidor via QUERY para cache e semântica.
• Não esqueça a ergonomia do SDK: Normalize objetos de filtro e ofereça um builder estável para que os clientes não gerem corpos únicos‑mas‑equivalentes que detonem seu cache.

6) Seu auth, WAF e rate limits são sensíveis ao método?

Pipelines de segurança rotineiramente tratam GET vs POST de forma especial. QUERY provavelmente herdará expectativas tipo GET, mas com um corpo que pode quebrar baselines.

• Ajuste de WAF: Inspecione limites de tamanho de corpo e parsers. Se você faz parsing de JSON para detecção de anomalias apenas em POST, estenda isso para QUERY ou perderá ameaças. Por outro lado, não gere falsos positivos demais em payloads QUERY benignos e mate seu p95.
• Modelo de CSRF: QUERY é seguro, mas navegadores ainda podem enviá-lo com credenciais. Mantenha sua proteção CSRF (cookies same‑site, tokens de double‑submit para rotas que mudam estado). Não faça whitelist apenas pelo método.
• Rate limits: Crie buckets separados para QUERY para não sufocar mutações sob cotas compartilhadas. Métodos seguros podem ter tetos mais altos com burst shaping mais rígido.

Um plano pragmático de migração

Fase 0: Inventário e baseline (2 semanas)

• Inventarie todos os endpoints de leitura com corpo hoje (POST‑usado‑como‑GET). Classifique por RPS e cacheabilidade (taxa de repetição, personalização, tolerância a TTL).
• Estabeleça a latência p50/p95 atual, tempo de CPU na origem e taxa de acertos na CDN para esses endpoints. Exponha um dashboard quebrado por método e rota para que os ganhos fiquem visíveis.

Fase 1: Endurecimento do caminho e canário (2–4 semanas)

• Rode o canário de pass‑through do método de ponta a ponta. Corrija regras de WAF e gateway. Adicione rótulos de método a logs, traces e métricas.
• Ensine sua borda a cachear não‑GET condicionalmente. No Fastly, isso significa lógica VCL/Compute@Edge; no Cloudflare, Workers/Rulesets. Comece com uma propriedade de staging e chaves sintéticas baseadas em um hash do corpo canonicalizado.

Fase 2: Rota dupla no principal candidato (4–6 semanas)

• Exponha sua busca de maior RPS e mais amigável a cache como POST e QUERY para um único handler. Normalize os corpos das requisições no servidor para uma representação canônica antes de acessar o storage.
• Roteie tráfego servidor‑a‑servidor para QUERY primeiro (serviços internos, cron, agentes). Mantenha navegadores em POST até medir o impacto de CORS/preflight.
• Ative TTLs conservadores na borda para QUERY (10–60s). Observe explosões de chaves e hot keys.

Fase 3: Expandir e otimizar (contínuo)

• Prossiga para os próximos 2–3 endpoints se você observar ≥15% de offload na origem e ≥20 ms de melhoria no p95 sem picos de erro.
• Aumente TTLs onde a correção permitir; adicione invalidação suave via refresh em background para evitar rajadas de stale após expiração do TTL.
• Aperte as cotas: Dê a QUERY um bucket maior, mas bursts por IP mais rígidos para proteger a infra de busca em picos de eventos.

Detalhes de engenharia em que você vai tropeçar (então corrija agora)

Regras de canonicalização

Implemente uma função única e compartilhada que transforme um objeto de filtro arbitrário em uma sequência de bytes canônica:

• Ordene chaves recursivamente, remova arrays vazias e nulls, coerça números para um formato fixo, trave faixas aos limites impostos pelo servidor.
• Serialize para JSON compacto (sem espaços) e faça hash (ex.: SHA‑256) para o componente de chave de cache.
• Documente essas regras publicamente para que clientes prevejam o comportamento e evitem cache misses.

Paginação e consistência

QUERY torna tentador fazer cache de resultados paginados. Faça, mas defina a consistência:

• Se você promete “majoritariamente fresco”, mire um TTL de 10–30s e aceite pequena defasagem em inventários que mudam rápido.
• Se você precisa de read‑your‑writes, não faça cache de visões específicas por usuário ou adicione um bypass de cache quando a sessão tiver escritas recentes (ex.: nos últimos 5s).
• Use paginação por cursor estável; inclua o cursor na canonicalização para evitar misturar páginas incompatíveis.

Correção da busca e backends vetoriais

Se você estiver expondo backends heterogêneos (SQL para filtros, DB vetorial para relevância), centralize a fusão no handler de QUERY. Faça cache apenas do ranking final, já mesclado, e não de parciais, a menos que você tenha benefício comprovado em empilhar caches parciais. Na prática, a maioria das equipes supercomplica isso; comece simples.

Analytics e SLOs

Inclua QUERY nos seus golden signals e error budgets. Não esconda em “outros”. Crie dashboards que separem explicitamente performance por método e offload da origem. Para resposta a incidentes, garanta que runbooks e páginas de status para clientes conheçam QUERY; você terá menos falsos alarmes se a equipe puder ver que uma regra de cache específica de QUERY está se comportando mal em vez de “a API está lenta”.

Ergonomia de SDK e agents

Agents são clientes barulhentos. Pequenas diferenças na serialização destroem caches. Entregue um cliente fino que:

• Canonicalizar os corpos das requisições no cliente antes de enviar.
• Aplique padrões conservadores: tamanhos de página limitados, filtros deduplicados, ordenação estável de campos.
• Tente novamente com segurança usando backoff exponencial em falhas de rede (QUERY é idempotente — use isso).

Trade-offs que você não deve ignorar

• Maturidade do ecossistema: Ferramentas, OpenAPI e SDKs prontos ainda não “falam” QUERY completamente. Você vai escrever glue code e extensões. Reserve tempo para isso.
• Imposto de preflight no navegador: Se seu front‑end é cross‑origin, espere 1 RTT extra em chamadas frias a menos que você reestruture o hosting ou ajuste o cache de CORS.
• Surpresas de middlebox: Algumas redes corporativas e proxies antigos ainda engasgam com verbos desconhecidos. Mantenha fallbacks em POST para fluxos críticos até que sua telemetria prove que é seguro remover.
• Disciplina de correção de cache: Quando corpos passam a participar das chaves de cache, descuido dói. Sem canonicalização e trilhos de proteção, você transformará sua CDN em uma máquina de explosão de chaves.

Como é o “bom” no final

Após um rollout disciplinado, eis o que você deve ver nos gráficos:

• Principais rotas de busca e navegação movidas de POST para QUERY (ou em dupla exposição), com taxas de acerto na borda entre 20–40% e CPU na origem para caminhos de leitura reduzida em 10–25%.
• p95 em listas/buscas reduzido em 30–80 ms para usuários globais; picos de cauda reduzidos durante surtos de tráfego.
• Alertas mais limpos: menos falsos positivos no WAF; páginas de incidente que conseguem isolar rapidamente regressões específicas de QUERY.
• Adoção de SDK: 80%+ dos serviços internos e agents usando o cliente canônico, com payloads amigáveis a cache.

Onde equipes nearshore entram

Este é um projeto perfeito para um pod nearshore focado: networking, gateways, lógica de borda, ergonomia de SDK e ajustes de observabilidade. É transversal e requer sobreposição de horário comercial com times nos EUA para mexer com segurança na configuração da borda (planejamos cerca de 6–8 horas de overlap). O trabalho não é glamouroso, mas se paga via economia de infra e um modelo mental mais simples para todos que constroem sobre sua API.

Recomendação

Se seu produto hoje tem tráfego de leitura relevante em POST‑com‑corpo, pilote QUERY neste trimestre. Comece servidor‑a‑servidor, mantenha fallbacks em POST no navegador até sua história de CORS estar limpa e exija canonicalização desde o dia zero. Use regras de cache explícitas, monitore seu espaço de chaves e torne os ganhos visíveis para finanças e produto. Se suas leituras são majoritariamente personalizadas ou próximas de escrita, você pode esperar — apenas pare de adicionar novos endpoints POST‑como‑GET. Desenhe-os como QUERY agora, mesmo que exponha POST temporariamente por compatibilidade.

Principais lições

• QUERY oferece semântica tipo GET com corpo de requisição — perfeito para leituras complexas sem hacks de URL.
• Ganhos reais: 20–40% de taxa de acerto de cache nos endpoints certos, 10–25% de offload na origem e ganhos de 30–80 ms no p95.
• Partes difíceis: middleboxes, lacunas em OpenAPI/SDK, preflight de CORS e disciplina de chaves de cache.
• Adote em fases: valide o método com um canário, faça rota dupla nos principais endpoints, comece por S2S e depois expanda para navegadores.
• Não espere o ecossistema ficar perfeito — apenas mantenha fallbacks em POST e publique regras de canonicalização.