Por que costumo não usar negociação de conteúdo

Artigo original ↗ Discussão no Hacker News ↗

Desenvolvedores web estão avaliando os benefícios e as desvantagens da negociação de conteúdo HTTP, especialmente quando usam a mesma URL para servir tanto HTML para humanos quanto JSON para máquinas. Muitos defendem separar endpoints de “hipermídia” (HTML) de APIs de dados JSON para evitar misturar preocupações de apresentação com interfaces públicas, simplificar o comportamento de cache/CDN e manter URLs previsíveis, mesmo que isso signifique abrir mão de algumas das funcionalidades mais abstratas do HTTP. Outros observam que, embora cabeçalhos como `Accept` e `Vary` possam lidar elegantemente com formatos e versionamento na teoria, ferramentas do mundo real, CDNs e práticas de equipe muitas vezes tornam abordagens mais simples baseadas em URL ou parâmetros mais práticas.

Negociação de conteúdo: utilidade e desvantagens

  • Alguns veem a negociação de conteúdo como necessária em casos limitados: escolher entre JSON/XML, binário vs JSON, ou múltiplos formatos de dados (CSV/TSV/Parquet), e em usos de web semântica/dados vinculados, onde o mesmo identificador deveria servir HTML para navegadores e JSON-LD/RDF para bibliotecas.
  • Outros argumentam que isso é exagero: JSON domina para dados, HTML para conteúdo, então a “negociação” acrescenta complexidade com pouco ganho. Muitos clientes não entendem bem os cabeçalhos Accept, e usuários reais muitas vezes preferem um simples parâmetro de consulta.
  • Várias pessoas acham conceitualmente confuso que a mesma URL e o mesmo método possam retornar formatos muito diferentes.

URLs, parâmetros de consulta e cabeçalhos

  • Muitos preferem URLs explícitas ou parâmetros de consulta (/item.json, ?format=json) por serem mais amigáveis para humanos, visíveis nos logs, fáceis com curl e favoráveis ao cache.
  • Os defensores dos cabeçalhos enfatizam que Accept é padronizado, permite preferências ponderadas e tipos de mídia personalizados (incluindo versionamento) e evita gambiarras de URL “stringly-typed”.
  • O debate continua sobre versionamento de API: segmentos de caminho como /v1/ são vistos como mais comuns e visíveis; outros preferem tipos de mídia versionados via Accept.

CDNs, cache e Vary/Accept

  • Vários comentários observam que a Cloudflare e outras CDNs frequentemente ignoram Vary (especialmente para conteúdo que não seja imagem), quebrando a negociação de conteúdo e fazendo com que variantes erradas do cache sejam servidas.
  • Alguns operadores de CDN restringem Vary por motivos de desempenho, tamanho do cache e distribuição de metadados. Isso empurra os praticantes para longe da negociação e em direção a endpoints separados.

Hipermídia vs APIs de dados; htmx vs SPAs

  • Muitos concordam com separar endpoints de “hipermídia/HTML para humanos” de APIs de dados/JSON para máquinas, para evitar misturar paginação, ordenação e preocupações específicas de UI em APIs públicas.
  • Fluxos renderizados no servidor/htmx são elogiados por permitirem que as equipes construam o app uma vez, evitem duplicar lógica em uma SPA em JS e adicionem comportamento rico com JavaScript mínimo.
  • Os céticos dizem que frameworks modernos do lado do cliente (por exemplo, React+TypeScript) oferecem padrões melhores, tipagem e localidade de código para UIs complexas, e veem padrões de hipermídia como desajeitados para apps sofisticados com estado.

O que conta como uma API?

  • Há discordância sobre a terminologia: alguns argumentam que APIs de hipermídia HTML fortemente acopladas não são realmente APIs para múltiplos clientes independentes, apenas parte do app; outros insistem que o HTML em si é uma API de rede para navegadores.