[Catalyst] REST - like uri design for CRUD

[Thomas L. Shinnick]

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> 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.scsys.co.uk/pipermail/catalyst/attachments/20080120/7fd5fb24/attachment.htm