HTTP Methods for RESTful Services http://www.restapitutorial.com/lessons/httpmethods.
html
Using HTTP Methods for RESTful Quick-Tips
Resource Naming
Services
The HTTP verbs comprise a major portion of our “uniform interface” constraint and provide us the action counterpart to the
noun-based resource. The primary or most-commonly-used HTTP verbs (or methods, as they are properly called) are POST,
GET, PUT, and DELETE. These correspond to create, read, update, and delete (or CRUD) operations, respectively. There are
a number of other verbs, too, but are utilized less frequently. Of those less-frequent methods, OPTIONS and HEAD are used
more often than others.
Below is a table summarizing recommended return values of the primary HTTP methods in combination with the resource
URIs:
HTTP
Verb Entire Collection (e.g. /customers) Specific Item (e.g. /customers/{id})
GET 200 (OK), list of customers. Use pagination, sorting and 200 (OK), single customer. 404 (Not Found), if
filtering to navigate big lists. ID not found or invalid.
PUT 404 (Not Found), unless you want to update/replace every 200 (OK) or 204 (No Content). 404 (Not
resource in the entire collection. Found), if ID not found or invalid.
POST 201 (Created), 'Location' header with link to /customers/{id} 404 (Not Found).
containing new ID.
DELETE 404 (Not Found), unless you want to delete the whole 200 (OK). 404 (Not Found), if ID not found or
collection—not often desirable. invalid.
Below is a more-detailed discussion of the main HTTP methods. Click on a tab for more information about the desired HTTP
method.
GET PUT POST DELETE
DELETE is pretty easy to understand. It is used to delete a resource identified by a URI.
On successful deletion, return HTTP status 200 (OK) along with a response body, perhaps the representation of the deleted
item (often demands too much bandwidth), or a wrapped response (see Return Values below). Either that or return HTTP
status 204 (NO CONTENT) with no response body. In other words, a 204 status with no body, or the JSEND-style response
and HTTP status 200 are the recommended responses.
HTTP-spec-wise, DELETE operations are idempotent. If you DELETE a resource, it's removed. Repeatedly calling DELETE
on that resource ends up the same: the resource is gone. If calling DELETE say, decrements a counter (within the resource),
the DELETE call is no longer idempotent. As mentioned previously, usage statistics and measurements may be updated while
still considering the service idempotent as long as no resource data is changed. Using POST for non-idempotent resource
requests is recommended.
There is a caveat about DELETE idempotence, however. Calling DELETE on a resource a second time will often return a 404
(NOT FOUND) since it was already removed and therefore is no longer findable. This makes DELETE operations no longer
idempotent, but is an appropriate compromise if resources are removed from the database instead of being simply marked as
deleted.
Examples:
DELETE http://www.example.com/customers/12345
DELETE http://www.example.com/customers/12345/orders
DELETE http://www.example.com/bucket/sample
This work by RestApiTutorial.com is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
1 of 2 10/04/2015 4:01
HTTP Methods for RESTful Services http://www.restapitutorial.com/lessons/httpmethods.html
2 of 2 10/04/2015 4:01
