focus on REST representations

2007-11-17 @ 15:54#

to this point my Exyus engine has ignored two key pillars of REST architecture:

  1. multiple representations (XML,XHTML,PDF,etc.)
  2. hyperlinking media

the reasons are many. first, conneg is just a mess for common browsers. this complicates (but does not eliminate) the process of serving multiple representations to clients. i like the notion of using URLs without the mime-type cruft (/path/document instead of /path/document.html). however, doing that *and* negotiating the content/mime-type with browsers is broken (for example, MSIE always sends Accept:*/* - feh!). so 'auto-conneg' is out.

there are some alternatives. for example, you can move the mime-type out of the header space and into the URL. the most common pattern is to include a mime-type 'tail' in the request (/path/document.pdf or /path/document.txt). another possibility is to place the mime-type in the path portion of the URL (/xml/path/document). finally, some sites opt to move the mime-type into the domain portion of the URL (xml.site.com/path/document). this last one seems very unpleasant.

it should also be pointed out that it's the *browser* that has the problems - not the server. for example, non-browser clients (command line apps, desktop executables, even javascript AJAX libraries) do offer full control over the Accept: header and, thus, conneg would be just fine. so, this is really about the browser, right?

one compromise that might work would be to offer not justthe 'clean' URL (/path/document) but also the 'mime-type' URLs (/path/document.html, /path/document.pdf, etc.). thus, browsers can be shown explicit URLs and use those, while 'smarter' clients can use the Accept: header with success. finally, any confusing requests (like from MSIE browsers[grin]) can fall back to the 'default' representation for that resource. it's got merit, but will proly be a code-mess [sigh].

so this all means a couple things. first, adding support for sniffing Accept: headers and acting accordingly (including returing 415 - Unsupported Media Type when appropriate). second, establishing a 'default' representation for URLs (seems kinda tedious, i think). third, coding the rules that determine when to fall back to that default media type (not too bad, really). once that is done, it needs to be rolled into my Exyus engine so that it 'just works' without any changes to existing clients.

i can see how it all can work. just not crazy about getting it all started...

code