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=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".
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: [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/
_______________________________________________
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/
