Practical issues with REST's use of the Accept header
December 14, 2011
In full blown REST, a
single resource can have multiple representations (formats). You
decide which representation to ask for and to serve by what is in
The issue I have with this in practice is that it makes the Accept header part of the name of the specific representation of the resource (okay, this is really the MIME type). You cannot talk about, for example, 'the URL of the Atom feed'; you must specify both the URL and the type when you are talking about it. By 'talk about' I mean more than just 'share with people'. Any time you want to retrieve a specific representation of the resource, the tools you use to do this must be told the type as well as the URL, or must default to the right type.
(And if the tool doesn't support specifying the type or has an awkward procedure for this, you lose.)
This is a problem. To start with, we simply don't have an agreed on notation for 'a URL in a specific type' in the same sense that we have a notation for 'an URL'. Names and notation are important, and lack of good notation is a serious drawback because (among other things) it gets in the way of communication. Communication between people, communication between people and programs, and communication between programs (and even inside programs).
Of course, REST has a good reason for doing this. From my outsider
perspective, the problem REST is solving is auto-discovering how to
retrieve a specific representation of a resource. If you have a base
URL, in a pure REST environment you now know how to retrieve any
representation of the URL that's available. Want a JSON or an Atom
feed version of URL <X>? Request <X> with an
Of course this raises questions in practice about what the equivalent of a URL is in another representation. For example, what is the proper Atom feed representation of the front page of a blog that shows only the most recent five entries: is it an Atom feed with only the five entries on the front page, or is it a full-sized Atom feed with more entries? I suspect that the proper REST answer is the former while most people would consider the latter to be more useful.
I'm a pragmatist. I care a lot about clear names and easy communication,
and I live in a world of imperfect tools (many of which were designed
Written on 14 December 2011.
* * *