Difference between PUT and POST

What's the difference between PUT and POST?

PUT vs POST: Idempotence

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.

FAQ

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