Chris's Wiki :: blog/web/PracticalRESTAccept

Practical issues with REST's use of the Accept header

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 HTTP Accept header of the HTTP request; if you want a HTML version of the URL you say that you will accept text/html and if you want a JSON version you ask for application/json (see eg).

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 Accept of JSON or Atom (or what have you) and you're done. And this works for any initial default representation; you do not have to assume, eg, an initial HTML representation where you then parse <link> elements out of the <head> to discover the Atom feed URL.

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 before the Accept type became important this way). Thus while I can admire the intellectual purity and usefulness of the full blown REST approach, I don't agree with it in practice and I'm not likely to build services that work that way (unless there's a compelling technical need to avoid the discovery problem). Even if it's less pure, I'll park my different representations of more or less the same thing on different URLs; it's simply easier in practice.

(One comment.)

These are my WanderingThoughts
(About the blog)

GettingAround
Full index of entries
Recent comments

This is part of CSpace, and is written by ChrisSiebenmann.

* * *

Atom feeds are available; see the bottom of most pages.

This is a DWiki.
(Help)

Categories: links, linux, programming, python, snark, solaris, spam, sysadmin, tech, unix, web

Written on 14 December 2011.
(Previous | Next)