Monday, October 24, 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.

See HTTP: The Definitive Guide  by David Gourley to learn more about idempotent and safe methods. Remember, strong knowledge of HTTP is key to success in REST.

Difference between PUT and POST in REST

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

You can further read REST in Practice book to learn more guidelines about designing a RESTful API. Sometimes reading a couple of books on the topic help to reduce confusion.

Difference between PST and PUT in REST

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 someone who prefer training courses and coaching classes than books, then you can also check out Eugen's REST with Spring course, it will teach you how to design REST API and develop RESTful Web Services using Spring Framework in Java. The course is very detailed and expects that you are familiar with Spring framework, so its ideal for intermediate and experienced Java and Web developers.

Eugen has severals options on his courses suited for different experience level and needs e.g. REST with Spring: The Intermediate class is good for essential knowledge while REST with Spring: The Masterclass is more detail oriented. You can check out all his course options here.

Other RESTful WebService articles you may like to explore
  • Restlet HelloWorld Example in Java and Eclipse (tutorial)
  • The difference between SOAP and RESTful web service in Java? (see here)
  • 15 REST Web Services framework Interview Question (see here)
  • What are idempotent and safe methods of HTTP and REST? (answer)
  • Top 10 RESTful web services interview questions for Java developers (see)
  • What is the purpose of different HTTP methods in REST? (answer)
  • Top 10 Java Web service interview questions (see here)
  • When to use PUT vs POST method in REST? (answer)
  • 3 ways to convert String to JSON Object in Java? (example)
  • 5 JSON parsing library Java and JEE developer should know (article)
  • 5 Books to prepare Java EE interviews (list)

Further Learning
REST Fundamentals By Howard Dierking
RESTFul Services in Java using Jersey


Shailesh Kumar said...

Nice !!!

Javin Paul said...

Thank you Shailesh, glad that you find these put vs post differences useful.

Venkat said...

Nice Post

Post a Comment