Father of HTTP and REST: REST APIs must be hypertext-driven

There was a link to an article posted yesterday or the day before on HN that attempted to interpret the original article. Here's the link:

http://www.25hoursaday.com/weblog/2008/10/24/RESTAPIDesignIn...

I have to admit it's still a bit confusing to me. However, look at this snippet extracted from a comment by the author of the article you provided:

"A truly RESTful API looks like hypertext. Every addressable unit of information carries an address, either explicitly (e.g., link and id attributes) or implicitly (e.g., derived from the media type definition and representation structure). Query results are represented by a list of links with summary information, not by arrays of object representations (query is not a substitute for identification of resources)."

And this snippet from the second:

"The latest drafts of the OpenSocial specification have a great example of how a service can use existing technologies such as URI templates to make even complicated URL structures to be flexible and discoverable without having to force every client and service to hardcode a specific URL structure."

This, to me, states that a restful api should implement api discoverability and give people a method to generate URI for any api call without hard-coding URIs into your code. A snippet from the article I linked-to that defines a URI template:

<os:URI-Template>http://api.example.org/groups/{guid}</os:URI-Template>

It's easy to imagine an api client transforming that template into a URI to retrieve group information without knowing about or caring about the specifics of the URI format -- it's a black box with the exception of '{guid}.' When provided with that information, a client can look at that template, substitute {guid} with an actual guid value, execute the URI, and get the desired results. This enables, amongst other things, the API to evolve without breaking the clients. The api clients must know how to interpret the set of template variable names used by the api ( guid, appid, selector, etc. in the example provided in the article), but that's it.

I'm sure there's more to it than that, but that's the part that resonated with me.

Yeah.. I think this is making it much to complex.

REST (for me) should simply be XML that you POST/GET/DELETE/PUT to/from a specific location - that specific location (i.e. the URI) is a specific resource.

Hence it should be http://example.com/cd/radiohead/okcomputer to read (GET) or write (PUT) that particular album entry... So basically you constrain the "nouns" to GET/PUT/POST/DELETE and make each URI a "verb" (CD, order, customer, Amazon product, whatever).

If you start breaking away from that, you quickly get back to the Web Services world, which is much more orientated around a transactional view than REST. (Web Services are better for these kinds of interactions imho).

So a funds transfer, or some kind of transactional processing probably isn't the best use of REST. The problem arises when people try to shoe-horn these kinds of things in regardless. It's quite difficult to do neatly with the nouns available.

Not that you can't break any of these rules and do it anyway... People do all the time. Hence (I think) why this author is so annoyed.

Either way, in my view, if you're going to use REST you might as well get the power of it's simplicity and avoid this type of shoehorning entirely. I'm a big advocate of using both REST and Web Services - use the appropriate technology for the given case.