Discussion on REST seems to be moving in a constructive direction all over the place with Tim Bray and Don Box both contributing. I think Dare Obasanjo’s notes from a talk given by Google’s Nelson Minar almost a year ago may have put some valuable terminology behind ideas that have been floating around for some time and may have even brought us to a place where we can have an actual conversation about this stuff:
To begin he defined what he called ‘low REST’ (i.e. Plain Old XML over HTTP or POX) and ‘high REST’. Low REST implies using HTTP GETs for all API accesses but remembering that GET requests should not have side effects. High REST involves using the four main HTTP verbs (GET, POST, PUT, and DELETE) to manipulate resource representations, using XML documents as message payloads, putting metadata in HTTP headers and using URLs meaningfully.
The definitions of low REST / high REST could be tweaked a bit (maybe they were when I wasn’t looking?)
but I do like the idea of putting terms we can all agree on to the
subset that’s the reality behind most of machine/web interfaces that
seem to be working today. POX
isn’t that term because it unnessarily constrains the media type; “low REST”
should include the mostly non-XML web (i.e. the
constraints of GET and POST.
The reason I like this approach is because it could remove the artificial and often harmful separation made between the web people interact with and the web machines interact with. Exposing resources for machine consumption isn’t any different than exposing resources for human consumption until you get down to the media type (and not then if you subscribe to Microformats). That is, some form of hyper-media (links / URIs) and a simple, universal interface (HTTP) are the really big wins you get with REST because those things are what creates the possibility of having a hugely distributed and uncoordinated system of interaction. The choice of document format is something else entirely and the decisions there ought to be based on a whole other set of concerns.
If I cared at all about the term anymore, I would go so far as to say that anything conforming to the constraints of at least one HTTP method and that also exposes references to other resources using URIs should be considered “a web service”. But “web service” has been defined to death and it doesn’t seem to be helping.
The first time I heard someone attempt to describe the GET/POST subset as something we should pay attention to was Michael Champion on xml-dev. This was usually thrown out when someone championing REST used the “REST is the web and the web is working” argument (I use that argument to this day, btw). Michael would often be the one to point out that it wasn’t exactly true and that a subset of what REST describes seemed to be working well on the web (GET/POST, URIs, caching), while another subset was clearly—sometimes knowingly—being violated (GET w/ side-effects, uncool URIs), and yet another subset was used only rarely (PUT/DELETE/OPTIONS, content negotiation).
Not being able to distinguish which of these subsets of applied REST one is refering to is hurting our ability to have meaningful conversations about this stuff. For example, consider the following conversation; I’ve seen it hundreds of times now:
Restafarian: 80% of developers use the XXX REST API because they find it easier to deal with.
Tool Vendor: That’s not really REST. It only uses GET and POST and breaks rule #5034
Restafarian: Oh yea, well SOAP/WS-* sucks.
Tool Vendor: Go write some PHP you dirty hippie!
I’d like that to stop happening.
But I don’t think adopting wrong or ambiguous terminology is going to help either. I’d like to register my nits with the few sentences that Dare provided and see if anyone else is thinking along similar lines.
To begin he defined what he called ‘low REST’ (i.e. Plain Old XML over HTTP or POX) and ‘high REST’.
Like I said before, POX is kind of, ummm, bad, I think. It focuses too much on the format. XML is not why the web is working. URLs and HTTP is why the web is working. HTTP and URLs work so well they’re even capable of being useful in spite of complexities in media-types based on XML.
Low REST implies using HTTP GETs for all API accesses but remembering that GET requests should not have side effects.
Fully constrained GETs are really important but POST should fall under low-REST too. By the definition above, low-REST can never modify anything. Throw POST in there, it’s a big part of the present day human/web and is likely to play a bigger role in the machine/web.
High REST involves using the four main HTTP verbs (GET, POST, PUT, and DELETE) to manipulate resource representations, using XML documents as message payloads, putting metadata in HTTP headers and using URLs meaningfully.
I think we ought to downgrade XML to a “
practice” or something. Microformats and JSON are two notable examples
of non-XML representations that seem to be working quite well and are
absolutely capable of being used high-RESTfully.
I’m pretty sure I’ll always be a high-RESTafarian but I could definitely see myself coming out as a lo-RESTafarian as well if some of this were grinded out a bit more.