[Catalyst] REST - like uri design for CRUD

[Ian Docherty]

Thomas L. Shinnick wrote:
> <SNIP>
> 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=3Dbreadbox
> 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".
I am just doing this now. The way I have implemented it is that an item =

is created by doing a POST to /class/create and the item is saved in the =

database. Then the browser is redirected to GET /class/id/1234 (for =

example) where the newly created item (with id 1234) can be read.

Now, this means that the client system will have a http response =

returned with 'status' '302' and 'location' '/class/id/1234' which I =

presume they will have to parse to determine the ID of the newly created =

item?

Is this correct?
>
> 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.u=
k/
> Dev site: http://dev.catalyst.perl.org/
>   =


-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.scsys.co.uk/pipermail/catalyst/attachments/20080126/77f01=
77a/attachment.htm