<html>
<body>
<font size=3>At 01:56 PM 1/20/2008, Zbigniew Lukasiak wrote:<br>
<blockquote type=cite class=cite cite="">I know this has been discussed
already - but I can't find it in the archives.<br><br>
What I conjured is:<br><br>
/class/search<br>
/class/id/1111/view<br>
/class/id/1111/update<br>
/class/create<br><br>
Update and create use really the same logic and templates - so I
just<br>
forward to a create_or_update action from them.<br><br>
What are your opinions?<br><br>
-- <br>
Zbigniew Lukasiak</blockquote><br>
<spew register="pedant"><br><br>
The book "RESTful Web Services" has been very useful to me in
understanding the confusion about what REST means when it comes to
'verbs'. And that I'm interested in how close one can come to
'strict' REST design using Catalyst.<br><br>
One important topic in the book is that people mix 'verbs' into their
URIs when they shouldn't, or at least when they don't _have_ to.
Using the book's concepts your URIs would become<br><br>
1) GET /class?pattern=breadbox<br>
2) GET /class/id/1111<br>
3) PUT /class/id/1111<br>
4) POST /class<br><br>
1) is your "/class/search" and says "let me retrieve the
representation/list of the items selected by searching for the given
pattern", where the base URI would indicate the set/list of items,
and the pattern is kept in the query parameters because it could be
anything. Note that the idea is that "GET /class"
references the list of all items, and you here are just qualifying that
search with the pattern.<br><br>
2) Your "/class/id/1111/view" would be seen in strict REST as
just a GET of "/class/id/1111". The HTTP 'verb' GET
already says give me a representation of the item. Done.<br><br>
3) Your "/class/id/1111/update" would become a PUT of
"/class/id/1111", where the new representation coming from the
remote client would _replace_ the old representation/data for that
item. This strict use of the HTTP 'PUT' verb is actually the
hardest to accomplish, as it assumes that the remote client can receive
and update a representation on the client, and then send it back using
PUT. It is easiest to picture this usage when the client completely
replaces the old representation held on the server. (see farther
below for why)<br><br>
4) Your "/class/create" becomes a POST to
"/class". This was another concept brought out by the
book. The matter of "who determines the item's 'id'" is
important. Here we assume that the _server_ will determine the id
of the new added item. You do a POST to the base URI of the data
area, and the server determines the new id, stores the data into the
item, and does a redirect to tell the remote client where the new item
is, that is, what is the new item's URI, for instance
"/class/id/1234".<br><br>
Why is "who determines the id" important? Because it says
what HTTP verb you should use to create a new item. If the server,
you use POST to "add another" item. (Much discussion of
"that most misunderstood of HTTP methods: POST" in the
book) But if the remote client were to determine the id, say
because the id is a license plate number input at the client, then strict
REST would say the client should do a PUT to
"/class/id/STRWBYP" and the client would send the complete data
for the item. The server would create the item using the id
'STRWBYP" as requested by the client.<br><br>
Creation using POST would say create a new item and tell me (the client)
where you (the server) put it. Creation using PUT defines where to
put it to the server, because the client knows what the id should
be.<br><br>
So under some designs it is possible that PUT will be used for both
creation of new items and update (replacement) of existing items.
In both these cases (under such a design) the client knows the correct id
for the item. <br><br>
Anyway this spew was prompted by the new pedant seeing 'REST' in the
subject and then no mention of 'PUT', etc. The book tries to be
clear that it depends on both your design and the >>capabilities of
the client<< whether you can implement using the strict REST HTTP
verb set GET, PUT, and POST, or whether you must compromise on a
REST-like set of GET and POST. The authors discuss how to
"overload POST" to effect PUT-like usage, because we have to
implement in the real world. But they are clear about the goals of
RESTful design, the problems it solves, and the benefits it brings
"in the real world". <br><br>
It looks to be very useful to consider URI design with a view towards
"how would I accomplish this by splitting my data objects into URI
addressable data that can be manipulated using the full set of HTTP verbs
GET, PUT, POST and HEAD. (And not putting verbs into URIs that
might be cached)"<br><br>
</spew></font></body>
</html>