essay, Uncategorized

Content negotiation considered harmful

Matilda, 1996

Content negotiation is a feature of HTTP that lets clients ask for, and servers return, different content types based on the request’s Accept header.

Sounds great, right? Well, no. Content negotiation is the classic example of an idea that sounds good in theory, but for the vast majority of web developers, turns out to be net harmful in practice. A few reasons:

  • Most web developers are not aware that conneg exists. This is usually fine, since it’s uncommon, but can be an unpleasant surprise when they first hit it and don’t understand it.
  • The Accept header is notoriously complicated to parse, generate, and fully comply with. Imo much of that complexity is unneeded in practice.
  • It often breaks caching when it’s first introduced. Internal and external caches generally ignore Content-Type and Accept (etc) by default, so when conneg is first introduced, clients often get the wrong response type. Developers learn the hard way that they need to add Accept to Vary and to their framework’s cache.
  • URLs leak across contexts. They may start out within a single service or API, but they gradually proliferate into user-visible links, object identifiers in other systems, add-on services, third party tools, etc. These generally don’t know the original conneg requirements, which causes unpleasant surprises.

I think most of this boils down to: modality generally considered harmful. When something always behaves the same way, it’s reliable and easy to use. When it behaves differently based on something far away that you may not know exists, it’s unreliable and surprising. Add in a very large ecosystem of independent tools that all need to interoperate, often in fine-grained ways, and you have a recipe for failure.


5 thoughts on “Content negotiation considered harmful

  1. Pingback: Links 26/03/2023: MidnightBSD 3.0 and FreeBSD 13.2 RC4 | Techrights

  2. From Frequently Observed Problems on the Web of Data:

    Beware! Content negotiation sounds great in theory, but it is a mess in practice. Implementing it correctly is surprisingly hard, or impossible if your server environment is restrictive, and it causes confusion to no end for people trying to access your server. So think twice before you use content negotiation, and avoid it if it’s not necessary.

  3. Ah, I see the problem. This is a bad interaction between caching and HTTP content negotiation. The WordPress ActivityPub plugin uses the post URL as…


  • 💬 Baldur Bjarnason

Leave a Reply

Your email address will not be published. Required fields are marked *