The following is just a reminder to stop me from getting confused 😉
- Used to fetch a resource.
- The server sends back a representation of the resource in the response body.
- Safe operation (see below).
- 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).
- 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.
- 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”
- 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.
- 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.