The one true REST explanation

I'm with him until he gets to "Hypermedia Controls", which strikes me as needless bureaucracy.<p>The 'link rel = "royalhope.nhs.uk/linkrels/slot/book"' element isn't really helping anything. Before you can consume that service, you need to know what "royalhope.nhs.uk/linkrels/slot/book" actually means, and if you already know that, then having it listed here in the response justs wastes space.<p>He's disguising a custom verb under a cloak of some sort of 'standardization' which isn't actually part of HTTP or any common web practice. The consumer of this service will need to know what all the verb URIs mean and precisely how to use them anyway, so listing them here doesn't provide any benefit and significantly complicates the communication.<p>In this way, the "Hypermedia Protocol" doesn't demonstrate any edge over old-school XML RPC.<p>Up until that point, I agreed with the article. Simple objects exposed using standard HTTP verbs is the way to go -- but I stop short of supporting random lists of verbs labeled with URIs as just more needless bureaucracy.

I find it hard to believe that he's built real systems that work.<p>Yes, "decomposing services into multiple components" works well when everything is living in the same address space, but if you want to build fast and reliable systems, minimizing round trips is important.<p>If I didn't have anything better to do and if I liked dealing with idiots, I'd hang my shingle as a high-priced consultant who helps "enterprises" dig their way out of the REST morass. Just last year I managed to speed up an application 100x by switching from REST to POX. In this case, the app was doing thousands of round trips for no good reason other than architectural purity.<p>In the real world, composite operations should be done, more or less, in transactions. For instance, in one user authentication system I've worked on, there are about ten database updates to create a new user. There really ought to be one "createUser" call that creates the user. You could probably get away with not having database transactions if you're talking to the database locally, but in a distributed app on the wider internet, you just can't expect to do ten communications in a row and have it work "reliably enough".

It's always seemed to me that the difficulty with hypermedia controls is not how to have your server expose them, which is straightforward enough, but how to have your client do something useful with them.<p>It basically means writing your client as a state-graph navigating agent, which makes it closer to AI-ish programming (not surprising, since the argument for REST has been that web services should be structured more like the human-browsable web) than the input -&#62; output or interactive event-driven paradigms that most programmers are more conversant with.<p>Yet the books and online evangelism etc. for REST that I've seen don't really address this issue.

This stuff isn't new, it just isn't widely adopted yet.<p>OpenSearch does stuff like this: <a href="http://www.opensearch.org/Specifications/OpenSearch/1.1/Draft_4" rel="nofollow">http://www.opensearch.org/Specifications/OpenSearch/1.1/Draf...</a><p>It describes an interface (Atom XML based) that further self-describes how it was called and what you can do to it (how to search within results, for example).<p>Simply applying that thinking to JSON based RESTful services gives you that question "What can I do with this?", and that makes building the API easier... for everything you serve describe what can be done with it and how you were called.<p>This then totally de-couples the request from the client, the client can send many queries and not care about them, and get back something that encapsulates the state of the request (search terms), the state of the result (search pagination) and the verbs for each entity (what you can do with it).<p>I never would've called this "Hypermedia Controls", I think that's confusing.<p>It's just having your interfaces describe themselves and be discoverable. Coupled with a WADL-style thing (but probably not WADL itself... perhaps JSON such as on the Freebase API: <a href="http://code.google.com/p/google-refine/wiki/ReconciliationServiceApi#Service_Metadata" rel="nofollow">http://code.google.com/p/google-refine/wiki/ReconciliationSe...</a> ).<p>Perhaps we all just need a new catchphrase or buzzword though, just to get the wider industry onboard? I'd rather just say that your services should be discoverable, and that means within the results telling us what we can do, in addition to a top level thing to describe which services exist.

Are there any good examples out there of services that implement that last level? I have seen and used the others but not discoverability.

This is one of the best (but simple) explanation of REST.

nice writeup. caucho's "metaprotocol taxonomy" is great further reading, contrasting REST with other common patterns/protocols: <a href="http://hessian.caucho.com/doc/metaprotocol-taxonomy.xtp" rel="nofollow">http://hessian.caucho.com/doc/metaprotocol-taxonomy.xtp</a>

I don't know if he had intended to put the REST zealotry to rest, but Martin Fowler and Roy field seem to be on the same page when it comes to level 2 REST. I submitted this to HN a few weeks ago, I'm posting it here again:<p><a href="http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post" rel="nofollow">http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post</a><p>I hope these 2 blog posts will just stop people from equating REST to full HTTP.

curious: why is the initial resource used to get the list of slots /doctors/mjones/slots?date=20100104&#38;status=open and not /slots?doctor=mjones&#38;date=20100104&#38;status=open?<p>if i am setting up future communications at /slots/1234, to me /slots?doctor=mjones&#38;date=20100104&#38;status=open makes more sense. would you typically just have both resources available at those locations?

I kind of expected the XML to disappear in level 3. In its current form, this is a non-standard extension to HTTP.