On 9/26/07, Dave S. [email protected] wrote:
<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.