Difference between PUT and POST in REST Web Services in Java - Example

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 operations in REST WebServices, Idempotency is the main difference between PUT and POST. Similar to the GET request, the PUT request is also idempotent in HTTP, which means it will produce the same results if executed once more multiple times. Another practical difference between PUT and POST methods in the context of REST WebService is 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 then 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 that says that for creating new things, you should use PUT if the unique identifier is provided by the client i.e. the client is responsible for creating an entity e.g. client can create resource /user/joe/ by providing username joe and that would be unique URI. Similarly, use POST if the server is responsible for creating new resources e.g. if the ID is part of URI and automatically created by the server.

And, if you are a complete beginner into RESTful web services then I also suggest you take a look at the Master Java Web Service and RESTful API with Spring Boot course by Ranga Rao on Udemy. It's a great hands-on course to learn how to develop RESTful web service in Java.

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 requests multiple times, it will end up creating 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 the 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 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, it's quite likely that your POST request may timeout, what will happen to the resource that. Is the resource actually updated? Does the timeout happen 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.

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 like Order, Book, Employee

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

4) Examples
PUT /items/1 update
POST /items create

You can further read the 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.

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 the 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 the client uses to send username=john and ID will be automatically generated by Server.

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 prefers training courses and coaching classes to 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 the Spring framework, so it's ideal for intermediate and experienced Java and Web developers.

Eugen has several options on his courses suited for different experience levels and needs like 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)
• Top 10 Java Web service interview questions (see here)
• When to use the 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)
• 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)

Thanks for reading this article so far. If you like my answer and explanation about PUT vs POST in REST then please share with your friend and colleagues on Twitter, I really appreciate it.