[Catalyst] REST - like uri design for CRUD

[Zbigniew Lukasiak]

On Jan 20, 2008 10:33 PM, Thomas L. Shinnick <tshinnic at io.com> wrote:
>
>
>
> 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

While we are at that - I do understand the need to divide the
operations into the 'indempotent' and 'non-indempotent' classes
(because of caching and predictive link loading) - but what is really
the practical argument for having two more classes (PUT and DELETE)?

Cheers,
Zbigniew




>
>  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: Catalyst at lists.scsys.co.uk
> Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
> Searchable archive: http://www.mail-archive.com/catalyst@lists.scsys.co.uk/
> Dev site: http://dev.catalyst.perl.org/
>
>



-- 
Zbigniew Lukasiak
http://brudnopis.blogspot.com/