Difference between PUT and POST in Java REST API

1. Introduction

In the context of Java REST APIs, PUT and POST are HTTP methods used to send data to the server. PUT is typically used to update a resource entirely or create a resource if it does not exist and the client is specifying the resource ID. POST, on the other hand, is used to create a new resource without the client specifying the resource ID, or to trigger operations that do not necessarily create resources.

2. Key Points

1. PUT is idempotent, meaning multiple identical requests should have the same effect as a single request.

2. POST is not idempotent, and making multiple identical requests will typically result in different outcomes.

3. PUT replaces the entire resource or creates a new one if it doesn’t exist at the specified URL.

4. POST is used to create a new resource or submit data to the server for processing.

3. Differences

PUT	POST
Idempotent: Repeated requests with the same data will produce the same result and will not change the state after the first request.	Not idempotent: Repeated requests can have different outcomes and may lead to the creation of multiple resources or different states.
Primarily used for updating existing resources. If the resource does not exist, PUT may create it.	It is primarily used for creating new resources. It can also be used for update operations but is not the conventional method.
The URI in a PUT request typically points to the specific resource to be updated.	The URI in a POST request points to the collection that will handle the creation of the new resource. The server typically assigns the new resource's URI.
Client-determined location: The client decides the URI of the resource to be created or updated.	Server-determined location: The server decides the final URI of the newly created resource, usually returning it in the response header.
Example use case: Updating the details of a specific user where the user ID is known.	Example use case: Adding a new user to a system where the server assigns a new user ID.

4. Example

// PUT example to update user details
@RequestMapping(value = "/users/{id}", method = RequestMethod.PUT)
public ResponseEntity<Object> updateUser(@PathVariable("id") String id, @RequestBody User user) {
    // Code to update the user
    return new ResponseEntity<>("User is updated successsfully", HttpStatus.OK);
}

// POST example to create a new user
@RequestMapping(value = "/users", method = RequestMethod.POST)
public ResponseEntity<Object> createUser(@RequestBody User user) {
    // Code to create a new user
    return new ResponseEntity<>("User is created successfully", HttpStatus.CREATED);
}

Output:

// Response for PUT request
HTTP/1.1 200 OK
User is updated successfully
// Response for POST request
HTTP/1.1 201 Created
User is created successfully

Explanation:

1. The PUT example is a request mapping in a Spring controller that updates a user's details based on the provided ID. It's idempotent because the user details will be updated only once if you call it multiple times.

2. The POST example is a request mapping in a Spring controller that creates a new user. It's not idempotent because calling it multiple times will create multiple users.

5. When to use?

Use PUT when you want to update a resource or create a new resource at a specific URL. Subsequent identical requests should have no additional effect.

- Use POST when you want to create a new resource without specifying the URL or to submit data for processing to the server where the operation might result in creating a new resource.