At 01:56 PM 1/20/2008, Zbigniew Lukasiak wrote:
I know this has been discussed already - but I can't find it in the archives.
What I conjured is:
/class/search
/class/id/1111/view
/class/id/1111/update
/class/create
Update and create use really the same logic and templates - so I just
forward to a create_or_update action from them.
What are your opinions?
--
Zbigniew Lukasiak
<spew register="pedant">
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.
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
1) GET /class?pattern=breadbox
2) GET /class/id/1111
3) PUT /class/id/1111
4) POST /class
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.
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.
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)
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".
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.
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.
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.
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".
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)"
</spew>
_______________________________________________
List: [email protected]
Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/[email protected]/
Dev site: http://dev.catalyst.perl.org/
