Why I tend not to use content negotiation
No, I am not advocating you return HTML as a general purpose API, hypermedia makes for a bad general purpose API. Yes, I am advocating tightly coupling your web application to your hypermedia API. No, I do not think that we will ever fix how the industry uses the term REST Yes, I am advocating you split your data API and your hypermedia API up. The last point often strikes people who are used to a single, general purpose JSON API as dumb: why have two APIs when you can have a single API that can satisfy any number of types of clients? I tried to answer that question as best I can in the essay above, but it is certainly a reasonable one to ask. This is the act of "Content negotiation" and it is certainly an interesting feature of HTTP. #Using Content Negotiation In APIs. Your JSON API needs to be a stable set of endpoint that client code can rely on. Taking all of this into account, as well as things like rate-limiting and so on, I think you can make a strong argument that there should be a Separation Of Concerns between the JSON API and the hypermedia API. #So What's The Alternative? The alternative is, as I advocate in Splitting Your APIs, er, well, splitting your APIs. This is why I prefer to split my JSON and hypermedia APIs up into separate controllers, rather than use HTTP content negotiation to attempt to reuse controllers for both.