PUT and POST are two common HTTP methods used to send data to a server. While they seem similar on the surface, there are some key differences between PUT and POST requests.
Summary of Differences
Here is a quick overview of the main differences between PUT and POST:
| PUT | POST |
| Used to update an existing resource | Used to create a new resource |
| Idempotent – calling it multiple times produces the same result | Not idempotent – calling it multiple times creates multiple resources |
| Requires the entire resource representation to be sent | Can send partial representation |
| Returns 200 OK on success | Returns 201 Created on success |
Let’s explore each of these differences in more detail.
Purpose of PUT vs POST
The core difference between PUT and POST is in their purpose:
- PUT is used to update an existing resource. The request payload contains the updated data that overwrites the existing data.
- POST is used to create a new resource. The request payload contains the data to create the new resource.
For example, if you had an existing blog post with id 123 that you wanted to update, you would send a PUT request to /posts/123 with the updated blog content. If you instead wanted to create a new blog post, you would send a POST request to /posts with the new blog content.
Updating Resources with PUT
When you want to update an existing resource, PUT is the appropriate HTTP method to use. The URI will include the resource ID to identify the specific resource to update. The request payload will contain the complete updated representation of the resource.
For instance, to update a product with id=432, you would send a PUT request to /products/432 containing the updated product information to overwrite the existing data. The server would find the product 432, see it already exists, and replace it entirely with the new product data from the request.
Creating Resources with POST
When you want to create a new resource on the server, POST is the appropriate HTTP method to use. The URI will specify the collection where you want to create the resource, but will not include an ID since the resource does not exist yet.
For example, to create a new product, you would send a POST request to /products with the new product data as the request payload. The server would generate a new unique id for the product, add it to the products collection, and return the id in the response.
Idempotence
An important behavioral difference between PUT and POST is that PUT is idempotent, while POST is not.
An idempotent HTTP method is one that produces the same result no matter how many times it is called with the same input parameters. PUT is idempotent because calling it multiple times with the same data should just overwrite the resource with the same update each time.
POST is not idempotent, because making multiple identical POST requests will create multiple new resources – i.e. calling POST /users multiple times with the same data will create multiple new user accounts.
Idempotence Examples
Here are some examples to demonstrate the idempotent nature of PUT compared to POST:
- PUT request to /users/123 called 3 times with the same data will still just update that user once.
- POST request to /users called 3 times with the same data will create 3 new user accounts.
This is an important consideration for use cases like ensuring retries and handling network errors. Retrying a failed PUT request will not cause any negative side effects, but retrying a failed POST could result in duplicate resource creation.
Request Payload
PUT and POST also differ in the kind of data representations they accept in the request payload:
- PUT requires the entire updated representation to be sent. The payload must contain all the attributes for the resource.
- POST can create a resource with just a subset of attributes sent in the payload. The payload does not have to be the full representation.
With PUT, you must send the full updated resource representation in the request. This replaces the existing resource attributes entirely. With POST, you can send partial data and the server will create the resource with those attributes.
PUT Payload Examples
Here are some examples of PUT payloads:
- Updating a product – Send entire product object with all attributes like id, name, description, price, images, etc.
- Updating a user profile – Send entire user profile object with all attributes like id, name, email, address, jobTitle, etc.
POST Payload Examples
Here are some examples of POST payloads:
- Creating a new product – Could just send name and description, let server generate id and set default price.
- Creating a user – Could just send name and email, let server generate id and leave other fields blank.
Status Codes
PUT and POST also return different success status codes:
- On successful update, PUT returns 200 OK.
- On successful resource creation, POST returns 201 Created.
This helps distinguish creation vs update on the server side. POST returning 201 confirms a new resource was created. PUT returning 200 indicates an existing resource was updated.
PUT Status Code Example
PUT request to /users/123 to update user:
PUT /users/123
{
"name": "John Doe",
"email": "[email protected]"
}
Returns 200 OK to indicate user 123 was updated.
POST Status Code Example
POST request to /users to create new user:
POST /users
{
"name": "Jane Doe",
"email": "[email protected]"
}
Returns 201 Created to indicate new user was created at say /users/456.
Use Cases
Now that we’ve explored the core differences, when would you actually want to use PUT vs POST in an API?
Use PUT When
- Updating an existing resource – e.g., editing a product, updating a user profile
- Replacing an entire resource representation – PUT requires full payload
- Idempotence is important – retries/errors won’t cause side effects
Use POST When
- Creating a new resource – e.g., adding a new product, creating a new user
- Sending partial resource data is okay – POST allows partial payloads
- You want to distinguish creation from update – POST returns 201 Created
Best Practices
Here are some best practices around using PUT vs POST:
- Use PUT only for existing resource updates, not for creation. Avoid PUT requests to URLs that do not yet exist.
- Use POST to create new resources, where PUT would return 404 if resource does not exist yet.
- Distinguish update vs create based on existence of resource ID in URL, not request payload.
- Treat PUT requests as full replacements of the resource. Remove any missing attributes on the server side after PUT.
- After POST, send Location header with URI of the new resource that was created.
Client Implementation
The PUT vs POST differences impact how you would implement making the requests in a client application. Here are some guidelines:
- Use PUT only with known, existing resource URLs with ids. Avoid speculating resource paths.
- With POST, you may not know final resource URL since id is generated on server side.
- Retry failed PUT requests, as they are idempotent. Avoid retrying POST requests.
- With PUT, send entire updated representation in request body. With POST, can be partial.
- Check POST response for Location header and use URI of created resource.
Conclusion
In summary, there are some key differences in behavior between PUT and POST requests:
- PUT is for update, POST is for create.
- PUT is idempotent, POST is not.
- PUT requires full payload, POST can be partial.
- PUT returns 200 OK, POST returns 201 Created.
Understanding these differences allows you to use the correct HTTP method for a given use case, implement your requests properly, and handle responses correctly when designing both server and client sides of an API.