Why I tend not to use content negotiation

Original Article ↗ Hacker News Discussion ↗

Web developers are weighing the benefits and pitfalls of HTTP content negotiation, especially when using the same URL to serve both HTML for humans and JSON for machines. Many argue for splitting “hypermedia” (HTML) endpoints from JSON data APIs to avoid mixing presentation concerns with public interfaces, simplify caching/CDN behavior, and keep URLs predictable, even if that means foregoing some of HTTP’s more abstract features. Others note that while headers like `Accept` and `Vary` can elegantly handle formats and versioning in theory, real-world tooling, CDNs, and team practices often make simpler URL- or query-based approaches more practical.

Content negotiation: usefulness and drawbacks

  • Some see content negotiation as necessary in limited cases: choosing between JSON/XML, binary vs JSON, or multiple data formats (CSV/TSV/Parquet), and for semantic‑web/linked‑data use where the same identifier should serve HTML to browsers and JSON‑LD/RDF to libraries.
  • Others argue it’s overkill: JSON dominates for data, HTML for content, so “negotiation” adds complexity for little gain. Many clients don’t understand Accept headers well, and real users often prefer a simple query param.
  • Several people find it conceptually confusing that the same URL and method can return very different formats.

URLs, query parameters, and headers

  • Many prefer explicit URLs or query params (/item.json, ?format=json) as more human‑friendly, visible in logs, easy with curl, and cache‑friendly.
  • Supporters of headers stress that Accept is standardized, allows weighted preferences and custom media types (including versioning), and avoids “stringly‑typed” URL hacks.
  • Debate continues over API versioning: path segments like /v1/ are seen as more common and visible; others like versioned media types via Accept.

CDNs, caching, and Vary/Accept

  • Multiple comments note Cloudflare and other CDNs often ignore Vary (especially for non‑image content), breaking content negotiation and leading to wrong cached variants being served.
  • Some CDN operators restrict Vary for performance, cache‑footprint, and metadata‑distribution reasons. This pushes practitioners away from negotiation toward separate endpoints.

Hypermedia vs data APIs; htmx vs SPAs

  • Many agree with separating “hypermedia/HTML endpoints for humans” from “data/JSON APIs for machines” to avoid mixing pagination, sorting, and UI‑specific concerns into public APIs.
  • htmx/server‑rendered flows are praised for letting teams build the app once, avoid duplicating logic in a JS SPA, and add rich behavior with minimal JavaScript.
  • Skeptics say modern client‑side frameworks (e.g., React+TypeScript) provide better patterns, typing, and code locality for complex UIs, and view hypermedia patterns as awkward for sophisticated stateful apps.

What counts as an API?

  • There is disagreement on terminology: some argue that tightly coupled HTML “hypermedia APIs” aren’t really APIs for multiple independent clients, just part of the app; others insist HTML itself is a network API for browsers.