ha.dev.br: o primeiro método HTTP em dezesseis anos, documentado em português

Todo filtro de dashboard é um crime contra o HTTP

Você precisa buscar dados. A consulta tem filtros aninhados, ranges de data, uma lista de campos. É uma leitura: não muda nada no servidor. E aí vem a pergunta que qualquer pessoa que já construiu API conhece de cor. Qual método usar?

GET é o método semanticamente correto. Safe, idempotent, cacheável, e proxies entendem isso sem precisar de configuração. Só que GET não aceita corpo. Então a consulta inteira vai para a query string, e ela cresce.

A RFC 9110 recomenda que servidores aceitem pelo menos 8.000 octetos na request-line. Isso é um piso, não uma garantia. O Apache vem com 8.190 bytes por padrão, o Nginx com algo entre 4.096 e 8.192, e proxies corporativos costumam ficar em 2.048. Você descobre o menor limite da cadeia em runtime, normalmente com um 414 Request-URI Too Long atrás de um proxy que o seu test suite nunca vai reproduzir. URL também vaza: access log, bookmark, histórico do browser. Se a consulta carrega dado sensível, ele agora está registrado em todo salto do caminho.

Quando a URL estoura, todo mundo faz a mesma coisa: POST /api/orders/search. Resolve o limite e passa a mentir sobre a intenção. POST não é safe nem idempotent. Se a conexão cai no meio, nenhum cliente ou intermediário sabe se o estado mudou, e nada faz retry automático. Service mesh trata como escrita. Ferramenta de observabilidade classifica como mutação. Cache também não resolve: a RFC 9110 permite cachear resposta de POST apenas com freshness explícita e Content-Location batendo, e mesmo assim o que fica em cache serve GET e HEAD futuros. Duas chamadas idênticas a POST /search sempre batem na origem.

Sobra a terceira opção, que é a pior de todas. GET com corpo não é proibido pelo HTTP/1.1, mas a RFC 9110 é explícita na seção 9.3.1: conteúdo dentro de um GET não tem semântica definida. Na prática, proxy descarta o corpo em silêncio, WAF bloqueia por parecer tráfego malicioso e biblioteca cliente ignora sem avisar. O resultado é o pior tipo de bug: o request chega sem filtro, devolve dado errado e o time passa a tarde tentando entender por que funciona local e não funciona em produção.

O que a RFC 10008 resolveu

A RFC 10008 foi publicada em 15 de junho de 2026. É o primeiro método HTTP novo desde o PATCH, que saiu na RFC 5789 em 2010. Dezesseis anos sem método novo. Os autores são Julian Reschke (greenbytes), James Snell (Cloudflare) e Mike Bishop (Akamai).

A especificação não nasceu ali. O primeiro draft é de 2015 e se chamava SEARCH. Em novembro de 2021 o nome mudou para QUERY, para escapar da bagagem que SEARCH carregava do WebDAV. Foram onze anos entre o primeiro rascunho e a publicação.

A definição cabe numa frase: QUERY é um GET com corpo. Safe, idempotent, cacheável, com request body esperado.

O corpo define a pergunta e o Content-Type define o formato dela. O servidor deve rejeitar requests sem Content-Type ou com tipo inconsistente com o conteúdo. Para descoberta, existe um header próprio:

1
Accept-Query: application/json, application/graphql

A parte que mais muda para quem opera infraestrutura está no cache. A resposta de um QUERY é cacheável, mas a cache key precisa incorporar o conteúdo da request, não só a URI. Isso é bem mais complexo que cachear GET: o cache tem que ler o corpo inteiro antes de decidir se já viu aquela consulta. Dá para normalizar, reordenando chaves JSON ou removendo whitespace, e normalizar demais devolve o resultado da consulta errada.

Na prática, o que era isso:

POST /contacts/search
Content-Type: application/json

{"filter": {"city": "Berlin"}, "limit": 50}

vira isso:

curl -X QUERY 'http://localhost:3000/contacts' \
  -H 'Content-Type: application/json' \
  -d '{"filter": {"city": "Berlin"}, "limit": 50}'

Mesma requisição, método honesto.

Por que documentar isso em português

Quem procura o assunto hoje encontra a RFC em inglês, a thread do working group, dois ou três posts em inglês de quem acompanhou a padronização, e a documentação do framework se ele já suportar. Em português, quase nada.

O concorrente real do site não é outro site. É a pessoa concluir que o assunto não é urgente e continuar mandando POST /search como sempre fez. A entrega que o ha.dev.br tenta fazer é de tempo: entender em vinte minutos o que exigiria ler a RFC inteira em outro idioma.

O conteúdo está publicado em PT-BR e em inglês, com as mesmas páginas nos dois idiomas: o que é o método, o problema que ele resolve, como funciona, antes e depois, a leitura da spec, a linha do tempo, um FAQ e a página de adoção. Os exemplos executáveis cobrem curl, Go, Node.js, PHP e Python.

A página que sustenta o resto

A especificação existir não significa que o método funciona ponta a ponta. QUERY só chega ao seu handler quando todos os componentes entre cliente e servidor aceitam o método, e essa é exatamente a informação que ninguém mantém organizada em lugar nenhum.

A página /adocao existe para isso. Ela classifica linguagens e frameworks, servidores e proxies, CDNs e edge, browsers e clientes HTTP, ferramentas e infraestrutura, com uma legenda de quatro estados: funciona nativamente, funciona com configuração, suporte esperado, não funciona.

Junto vem a lista do que pode dar errado, que é a parte mais útil para quem vai testar. WAF e firewall corporativo mantêm allowlist de métodos e devolvem 403 ou 405 sem explicação. O AWS ALB pode responder 405 para método fora da lista padrão. O CloudFront tem allowlist explícita de métodos, e o que não está nela nem chega na origem. Framework opinado devolve 405 antes de chegar no handler. API gateway valida o método antes de rotear. E ferramenta de monitoramento tende a categorizar QUERY como unknown, o que quebra dashboard em silêncio.

A página também faz a conta de quanto tempo isso costuma levar, usando o PATCH como precedente. Primeiro draft em 2003, RFC em março de 2010, uso generalizado por volta de 2015 e 2016, suporte universal entre 2018 e 2020. Ou seja: cinco a seis anos do RFC ao uso comum, oito a dez até estar em todo lugar. A leitura para o QUERY é de três a cinco anos para API pública sem sustos. Para API interna, onde você controla a stack inteira, dá para começar hoje.

Como o site é montado

A stack é deliberadamente pequena, porque o projeto é conteúdo e não produto:

• Astro 7 com Starlight para a estrutura de documentação, navegação e sumário
• Conteúdo bilíngue em collection própria, com o português na raiz e o inglês em /en
• Pagefind para busca local, sem serviço externo
• Docker multi-stage servindo por nginx, com deploy em Coolify

Sobre o nome: não é Home Assistant

Vale registrar porque a confusão é previsível. O ha do domínio não é Home Assistant. O domínio saiu do coming-soon em 4 de julho de 2026 e foi redirecionado da ideia original para este projeto, com a releitura ha como HTTP Architecture ou HTTP API. A associação foi uma decisão, não um acidente.

O que também vale registrar é que o encaixe é fraco. Duas letras genéricas não carregam a promessa do conteúdo, e a maior parte do tráfego de marca de “ha” no Brasil pertence mesmo ao Home Assistant. O domínio funciona porque o conteúdo é encontrado por busca de tema, não por busca de marca. Ele não está ajudando; está apenas não atrapalhando.

Onde o projeto está hoje

O site está no ar, com o conteúdo completo nos dois idiomas. O que ainda não existe é resultado: o snapshot de 12 de setembro de 2026 registra 0 clique, 25 impressões e posição média 11,8.

O critério que vale para os próximos 90 dias é estreito de propósito. Ou a página /adocao passa a receber busca orgânica recorrente, ou o site aparece citado em resposta de LLM sobre RFC 10008. Sem um dos dois, o projeto vira arquivo histórico e o esforço de manutenção vai para outro lugar.

Visitar ha.dev.br · Ler a RFC 10008 · Consultar a RFC 9110