The following is just a reminder to stop me from getting confused 
GET
- Used to fetch a resource.
- The server sends back a representation of the resource in the response body.
- Safe operation (see below).
DELETE
- Used to delete a resource.
- The response from a server may contain a status message or nothing at all. It is usually nice to send back at least a 204 (No Content).
- Idempotent operation (see below).
PUT
- Used to create or modify a resource. If your server should not permit users to determine the URI of a new resource then you may need to create it via a POST to a factory service (see below).
- The request body contains the proposed new representation of the resource.
- From my reading there seems to be some contention as to whether the request body should contain a full representation of the resource or a delta when modifying an existing resource. My personal preference is that the request should contain a representation of the whole resource, and use a POST method to the resource to update part of a resource. Alternatively, if possible, you can PUT to a sub-resource (e.g. PUT to /user/12345/address if all I want to do is modify the user’s address).
- The response from a server may contain a status message or nothing at all. It is usually nice to at least return a 200 (OK).
- Idempotent operation.
POST
- Used to create subordinate resources: resources that exist in relation to some other parent resource.
- For example: POST /weblogs/myweblog with the request body containing the contents of a new weblog entry would create an entry called /weblogs/myweblog/entries/SS0093WSA.
- Response to such a POST request usually has a status of 201 (Created) and a HTTP response “Location” header that has the URI of the created resource.
- POST can also be used to append to an existing resource or to update an existing resource.
- For example: POST to /log adds a log message to the /log resource.
- Not safe or idempotent. Expect side-effects. “Here be dragons”
HEAD
- Used to retrieve metadata about a resource, rather than the resource itself.
- Can be used to check if the resource exists, or if a newer version of the resource is available.
- Gives you the same HTTP header as the response to a GET request, just without the response body.
- Safe operation.
OPTIONS and TRACE
- Currently not really used by most RESTful systems. Nobody can really figure out how to use them properly.
OPERATION TYPES
- Safe operation
- Should not change any server state – or at least any state that matters as even GET requests can get logged or access counters can become incremented.
- Idempotent operation
- Has the same effect irrespective of the number of times its applied. In other words, the second and subsequent requests leave the resource in exactly the same state as the first request did.
#1 by Justin Cormack on 10 November 2009 - 1:54 am
Quote
PUT does need the whole resource
PATCH is now under discussion again for partial updates
OPTIONS tells you which methods work it is useful
happy RESTing!
#2 by Tom on 10 November 2009 - 9:51 pm
Quote
Thanks Justin. I know that OPTIONS tells me what methods are useful, but what I really want to know is what I can do to/with an endpoint in terms of representations of request/response data, etc, and that’s the bit where OPTIONS would really excel, its just that nobody has figured out how to describe that in a useful and consistent manner.
#3 by Stephen Chu on 11 November 2009 - 6:57 am
Quote
Good, succinct summary. One question: did you mean “POST /weblogs/myweblog/*entries*” to create a new entry for myweblog instead? Because to me, POST-ing to /weblogs/myweblog is to create the (singular) resource “myweblog”. By singular, I mean the application can only have at max one instance of myweblog. (analogous to map.resource (singular) in Rails).
#4 by Tom on 11 November 2009 - 7:10 pm
Quote
Stephen, you are correct that the application should only have one representation of myweblog. That’s why I’m assuming that I want to POST the representation of a weblog to a factory resource at /weblogs/myweblog (which is the single instance). The factory resource creates a new weblog and assigns it the id SS0093WSA. The response is then a 201 with a “Location” header /weblogs/myweblog/entries/SS0093WSA, which is the URI to view the newly created weblog entry.
I could POST to /weblogs/myweblog/entries to create a new weblog which would be equally as valid and probably has less *magic* in it since it is a bit more clear that posting to /weblogs/myweblog/entries creates a new weblog entry. However in terms of subordinate resources as long as the generated resource is addressed somewhere under /weblogs/myweblog I can use the service at /weblogs/myweblog as a resource factory, its just less clear that it is a resource factory.
Conceptually if you perform a HTTP GET on /weblogs/myweblog you could get a representation of all weblog entries, or a redirect to /weblogs/myweblog/entries to get a list of all entries, or simply a 405 (Method Not Allowed) with an “Allow” header stating that you can only PUT requests are permitted.
#5 by Prodis a.k.a. Fernando Hamasaki de Amorim on 17 November 2009 - 10:26 pm
Quote
Good summary.