Tuesday, 8 November 2016

Difference between PUT and POST in REST WebService in Java

If you remember REST WebServices uses HTTP methods to map CRUD (create, retrieve, update, delete) operations to HTTP requests. Even though both PUT and POST methods can be used to perform create and update operation in REST WebServices, Idempotency is the main difference between PUT and POST. Similar to the GET request, PUT request is also idempotent in HTTP, which means it will produce the same results if executed once more multiple times. Another practical difference PUT and POST method in the context of REST WebService are that POST is often used to create a new entity, and PUT is often used to update an existing entity. If you replace an existing entity using PUT than you should be aware that if only a subset of data elements is passed then the rest will be replaced by empty or null.
There is also another theory which says that for creating new things, you should use PUT if the unique identifier is provided by client i.e. client is responsible for creating entity e.g. client can create resource /user/joe/ by providing username joe and that would be unique URI. Similar, use POST if the server is responsible for creating new resources e.g. if ID is part of URI and automatically created by the server.

Let's see a couple of more differences between PUT and POST in REST WebServices.

PUT vs POST in REST WebService 

As I said, even though both PUT and POST can be used to create and update an entity, POST is usually preferred for creating and PUT is preferred for updating an existing entity.

For example, to create a new Order you should use:

POST /orders

and to update an existing order, you should use

PUT /orders/13892

which means modify the order with OrderId 13892

If you execute POST request multiple times, it will end up create that many orders, but when you execute PUT it will always produce the same result because of its idempotent. You should also remember that both PUT and POST are unsafe methods. Safe methods in HTTP do not modify the resource in the server e..g GET or HEAD, while Idempotent HTTP methods return same result irrespective of how many times you call them.

Idempotency is an important thing while building a fault-tolerant RESTful API. Idempotency is also the reason of why you should use PUT over POST to update a resource in REST. For example, suppose a client wants to update a resource through POST. Since POST is not an idempotent method, calling it multiple times may result in incorrect updates.

In the real world its quite likely that your POST request may timeout, what will happen to the resource that. Is the resource actually updated? Does the timeout happened during sending the request to the server, or the response to the client? Can we safely retry again, or do we need to figure out first what has happened with the resource? By using idempotent methods like PUT, you don't have to answer this question, but we can safely resend the request until we actually get a response back from the server.

When to use PUT and POST methods in REST?

Now' it's time for some practical knowledge about when to use the PUT and POST methods to call RESTful WebServices.

1) You should use POST to create new resources and PUT to update existing resources.

2) Use PUT when you know the "id" of the object e.g. Order, Book, Employee

3) Use POST when you need the server to be in control of URL generation of your resources.

4) Examples

PUT /items/1 update
POST /items create

Btw, there is also another theory, which states that if the client is responsible for creating the ID's of the resource, use PUT to create new things e.g.

PUT /users/john

Here John is unique and given by the client, this is a new URI.

Similarly, if server is responsible for creating the ID's of the new resources then use POST, for example

POST /users/

Now, POST will carry a key and value which client uses to send username=john and ID will be automatically generated by Server.

Difference between PUT and POST in REST WebService in Java

That's all about the difference between PUT and POST HTTP methods in REST WebServices. You should remember even though both PUT and POST are not safe methods, PUT is idempotent. Which means it will return the same result even if you call multiple times. The general advice is that POST is used to create new objects and PUT is used to update existing objects. If you are designing RESTful APIs then I also suggest you reading REST in Practice: Hypermedia and Systems Architecture by Jim Webber, Savas Parastatidis, and Ian Robinson . This will give you lots of practical advice for designing your own REST API.