How to Assign HTTP methods to REST Resources

This is the third step in Design RESTful API. In this post, we will learn what is the use of HTTP Methods and how to assign HTTP methods to REST Resources.

In the previous post, we learned -

How to Identify REST Resources

How to Design URL to REST Resource

Let's understand the usage HTTP Methods GET, POST, PUT, DELETE and PATCH one by one. Finally, we will do a case study using HTTP methods.

GET

The HTTP GET method is used to 'read '(or retrieve) a representation of a resource. In the “happy” (or non-error) path, GET returns a representation in XML or JSON and an HTTP response code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST).

According to the design of the HTTP specification, GET (along with HEAD) requests are used only to read data and not change it. Therefore, when used this way, they are considered safe. That is, they can be called without risk of data modification or corruption—calling it once has the same effect as calling it 10 times or none at all. Additionally, GET (and HEAD) is idempotent, which means that making multiple identical requests ends up having the same result as a single request.

Do not expose unsafe operations via GET—it should never modify any resources on the server.

Examples:

GET http://www.example.com/customers/12345
GET http://www.example.com/customers/12345/orders
GET http://www.example.com/buckets/sample

POST

The POST verb is most-often utilized to 'create' new resources. In particular, it's used to create subordinate resources. That is subordinate to some other (e.g. parent) resource. In other words, when creating a new resource, POST to the parent and the service takes care of associating the new resource with the parent, assigning an ID (new resource URI), etc.

On successful creation, return HTTP status 201, returning a Location header with a link to the newly-created resource with the 201 HTTP status.

The POST is neither safe nor idempotent. It is therefore recommended for non-idempotent resource requests. Making two identical POST requests will most-likely result in two resources containing the same information.

Examples:

POST-http://www.example.com/customers

POST-http://www.example.com/customers/12345/orders

PUT

PUT is most-often utilized for **update** capabilities, PUT-ing to a known resource URI with the request body containing the newly-updated representation of the original resource.

However, PUT can also be used to create a resource in the case where the resource ID is chosen by the client instead of by the server. In other words, if the PUT is to a URI that contains the value of a non-existent resource ID. Again, the request body contains a resource representation. Many feel this is convoluted and confusing. Consequently, this method of creation should be used sparingly, if at all.

On successful update, return 200 (or 204 if not returning any content in the body) from a PUT. If using PUT for creating, return HTTP status 201 on successful creation. A body in the response is optional—providing one consumes more bandwidth. It is not necessary to return a link via a Location header in the creation case since the client already set the resource ID.

Examples:

PUT http://www.example.com/customers/12345
PUT http://www.example.com/customers/12345/orders/98765
PUT http://www.example.com/buckets/secret_stuff

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 nobody, or the JSEND-style response and HTTP status 200 are the recommended responses.

Examples:

DELETE http://www.example.com/customers/12345

DELETE http://www.example.com/customers/12345/orders

DELETE http://www.example.com/bucket/sample

PATCH

PATCH is used for **modify** capabilities. The PATCH request only needs to contain the changes to the resource, not the complete resource.

This resembles PUT, but the body contains a set of instructions describing how a resource currently residing on the server should be modified to produce a new version. This means that the PATCH body should not just be a modified part of the resource but in some kind of patch languages like JSON Patch or XML Patch.

Examples:

PATCH http://www.example.com/customers/12345

PATCH http://www.example.com/customers/12345/orders/98765

PATCH http://www.example.com/buckets/secret_stuff

Case Study 1

In this case study, let's take the Employee Management System(EMS) application. Let's analysis the EMS application and find out different resource operations.

Consider we have Employee entity so let's Identify Resources from Employee entity using step 1.

After identifying REST resources let's design the URL for REST resources by using step 2.

Now in this post, we will assign HTTP methods to REST resources.

1. Use GET method to retrieve employee object by id

Example : /api/v1/employees/100

2. Use GET method to retrieve employees.

Example : /api/v1/employees

3. Use POST method to post employee object

Example : /api/v1/employees

4. Use PUT method to update employee object by id and pass employee object as JSON

Employee : /api/v1/employees/100

5. Use PATCH method to update employee object partially.

Conclusion

In this post we learned how to assign HTTP methods to REST resources.
In next step we will learn how to resource JSON format(Representation like JSON, XML etc.).
Related Posts