<Dave's Rant Snipped>
REST-as-religion gets annoying alright, but be clear - the religious aspect is not coming from the chief advocates, but the recently converted.
The main problem you are arriving at, is that much of the stuff on REST is highly academic, and REST web services are not widely supported in many web frameworks (only the good ones). In particular the Java guys haven't generally drunk the Kool-aid, so that massive pool of developers have so far been absent from the discussion.
Okay. In order to simplify my post, let's just pretend I'm developing a lightweight social networking site, and I have Users and UserProfiles (with the obvious has_one association). Is it considered "RESTful" if I have these following routes? Is the "RESTful" requirement simply that there is some cacheable URI for each thing for each of the CRUD operations?
I am not a RESTafarain (yet), but I think I grok it. Here's my take, hopefully others can address anything I get wrong:
The primary element in REST is the resource. Resources should be mappable to a URI, and interacted with exclusively by HTTP verbs. The URI is exclusively they way that you locate a resource. The same URI cannot be mapped to different resources and still be RESTful. (say if you were using cookies or sessions or something)
- So a RESTful route should not use the URL query string (anything after the ?) to identify the resource. (this isn't a hard and fast rule, you can use the query string and still be RESTful though its harder work)
- A RESTful route should *not* contain a verb. This is an absolute.
Home is only seen by the logged in user, and might have all sorts of "resource" information on it...
/user/home
Not RESTful. /user/home should always return the *same* resource in order to be restful. To achieve what you want to achieve, you would use the following:
/user/1/home /user/dsmith/home /user/rconroy/home /user/spiderman_045/home
or any variation of /user/${UNIQUE_USER_REFERENCE}/home
These guys represent 2 different "resources", UserProfile and Comment /username/profile
From above, if you do the following:
/davesmith/profile and /richard/profile
these are RESTful.
/username/profile;edit
Not RESTful. Verb in URI.
/username/comments?comment_id=1234
If you were being a REST fundamentalist, this isn't RESTful, but more practical RESTafarians recognise this as a necessary workaround in some cases. In a practical sense, you would probably use a simpler route format too:
/username/comments/1234
What if each user has a forum, but there is also a public forum?
/username/forum/thread?thread_id=1234 /forums/thread?forum_id=1234&thread_id=1234
Would those 2 routes constitute a "RESTful" interface?
There is a couple of misconceptions about REST.
- Every resource in your site has to be RESTful
People really struggle with this. And with good reason: it is impractical to implement everything as purely RESTful, when you expect to serve pages to browsers. You can't realistically have a form on every page, and browsers don't even support all the HTTP verbs anyway. So you end up using a lot of workarounds (AJAX, non-RESTful form resources that POST/PUT/DELETE RESTful resources etc.).
So you end up with /myforum/thread/12/post/12345 (RESTful)
to edit that post then: /myforum/thread/12/post/12345/edit (not-RESTful) However it is essential that the form actions point towards a genuine RESTful resource.
- People have trouble modelling their domain object hierarchies in a RESTful way
Well thats the thing - REST has no concept of this. As users of a RESTful web resource you expect that there is some logical hierarchy or naming convention of RESTful routes. But its just a convention imposed by the designer of that RESTful site.
REST only requires that your current resource denotes other related resources as URLs. Those other URLs do not have to be specialised forms of the current resource.
Consider a social networking site where I can list my friends: /users/rconroy/friends This returns a list of other users. However the links to those users have the form: /users/dsmith/profile /users/happygurl_12/profile /users/axelrod/profile
These are my findings to date. I hope this helps your understanding. I would also be interested in seeing what people who *really* know what they are talking about have to say about what I have said.