POST vs PUT In REST API

RESTful web services use HTTP methods like GET, POST, DELETE, and PUT to communicate with clients. The HTTP method determines how the server will respond to the request.

Criteria	POST	PUT
Use	Create a new record	Update a record
Idempotent	POST is non-idempotent	PUT is Idempotent
Request Body	POST sends the part to be updated in the request	PUT needs to send the entire resource as payload
Status Code	As new record gets created in each request, 201 is sent in response, 409 if duplicates are not allowed	200 when record gets updated, 201 if this record is new

PUT for update, POST for create

In general, the HTTP PUT method is used to update an existing resource, while the POST method is used to create a new resource. PUT requests are used to update a resource, while POST requests are used to create a new resource.

PUT /users/123
Content-Type: application/json

{
  "name": "John Smith",
  "email": "newemail@example.com",
  "password": "newpassword"
}

PUT is idempotent and POST is not

PUT requests are typically idempotent, meaning that multiple identical PUT requests will have the same effect as a single request. In contrast, POST requests are typically not idempotent, and multiple requests may have different effects. For example, if the first PUT request updates a record with a given updated data, subsequent duplicate request using the same data will not alter the system as it will update the same record with same data. However in POST request if duplicate data is sent, new records get created.

PUT sends entire body

PUT requests typically include the entire resource in the request body, while POST requests may include only the updated portion of the resource. So, PUT is used to modify the entire resource, so all the details in the resource should be sent in the PUT request. To modify specific part of the resource, PATCH method was created.

Here is an example of a PATCH request using the JSON format:

PATCH /users/123
Content-Type: application/json

{
  "email": "newemail@example.com",
  "password": "newpassword"
}

PUT doesn't need a body

There are two main differences between a POST request and a PUT request. First, a POST request must contain a body. Second, a PUT request does not require a body. A POST request sends data to the URL specified in the request. Unlike a PUT request, a POST request does not have an optional body. If the server receives a POST request without a body, then the server assumes that the client wants to send data to the server.

Status codes for PUT vs POST

PUT section of RFC 7231 states that it can return 201, just like POST request if the resource didn't exist on the server. But a POST request should always create a new resource and return 201 Created status code. If duplicates are handled on the server, POST may return 409 Conflict

If the target resource does not have a current representation and the PUT successfully creates one, then the origin server MUST inform the user agent by sending a 201 (Created) response. If the target resource does have a current representation and that representation is successfully modified in accordance with the state of the enclosed representation, then the origin server MUST send either a 200 (OK) or a 204 (No Content) response to indicate successful completion of the request.

It's important to note that the specific behavior of PUT and POST requests may vary depending on the API you are working with. Always refer to the API documentation for details on how these methods are intended to be used.