What's the difference between PUT and POST?
POST creates a resource, while PUT creates or updates a resource.
PUT URI identifies a specific resource entity for creation/updated, while a POST URI points to a group of resources that will handle the data.
PUT is idempotent, while POST is not.
|Creates or updates
|Creates or updates
|URI points to
|Specifies resource URI
|Specifies collection URI
|Used for actions (e.g.
|HTTP status code for successful request
200, 204 (modifying existing resource), 201 (creating new resource)
200, 204 (action performed, no new resource), 201 (new resource created)
|Can update or create resource
PUT vs POST: Idempotence
Idempotence is a property of a function or operation that yields the same result no matter how many times it is applied.
In web APIs and HTTP methods, idempotence means that if a client makes an identical request multiple times using an idempotent HTTP method, the server should return the same response for each request and should not create duplicate resources or modify existing resources in unexpected ways.
PUT is idempotent, meaning multiple identical requests will have the same effect as a single request. POST is not idempotent.
Why is PUT idempotent?
PUT is idempotent because a client sends the complete representation of the resource in the request body and specifies the URI of the resource to create or modify.
The server will either create the resource if it doesn't exist or update it with the new representation if it does exist.
Since the client is providing the complete representation of the resource, the server can update the resource to the exact same state as many times as needed without any unintended side effects.
Therefore, we can send the same PUT request multiple times with predictable outcomes.
Why is POST not idempotent?
POST is not idempotent because sending the same request multiple times may result in different server states each time.
POST URI points to a resource collection, not the specify resource URI. Sending the same POST request multiple times results in multiple resources being created, each with a different URI.
Unlike PUT, the internals of POST can change, so we cannot have predictable outcomes.
PUT vs POST: URI Structure
The POST method adds a new item to a collection, while the PUT method creates or updates a single resource.
This difference between a collection and a single resource is important for the URI structure:
When we make a POST request, we reference the collection URI, but when we make a PUT request, we reference the resource URI.
POST URI Structure
POST /users HTTP/1.1
PUT URI Structure
PUT /users/12356 HTTP/1.1
POST is not only used to create a resource, but also to perform an action.
PUT vs POST: HTTP Status Code
Created or updated?
REST APIs communicate results using HTTP status codes.
Using proper HTTP Status codes as defined in RFC 2616 is crucial to spot the differences between PUT and POST.
PUT Status Codes
For a successful PUT request, the server should return:
- 200 (OK) or 204 (No Content) if an existing resource is modified
- 201 (Created) if a new resource is created
POST Status Codes
For a successful POST request, the server should return:
- 200 (OK) or 204 (No Content) if an action is performed but new resource is not created
- 201 (Created) if a new resource was created
The 201 Created response should include a Location header that points to the newly created resource.
Can PUT be used to "update or create"?
Yes, the PUT method can be used for both updating an existing resource and creating a new resource.
When updating an existing resource, the PUT method replaces the entire resource with the new representation. If the resource does not exist at the specified URI, the server can create a new resource.
Why is it important to use a proper HTTP method?
HTTP methods are important piece of best practices in building REST APIs.
It's important to use the proper HTTP method to prevent unexpected behavior.
For example, using a POST request instead of a PUT request could result in the creation of duplicate resources or unexpected modifications to existing resources.
Read more: PATCH vs PUT
I've used these principles to increase my earnings by 63% in two years. So can you.
Dive into my 7 actionable steps to elevate your career.