Difference between PUT and POST

By Josip Miskovic
A thumbnail showing code. Everything you need to know about using PATCH vs PUT when building professional REST APIs.

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.

Differences between PUT and POST

Creates or updates Creates or updates Creates
URI points to Resource Resource collection
Idempotent Yes No
URI structure Specifies resource URI Specifies collection URI
Used for actions (e.g. /search) No Yes
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 Yes Yes

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.

RFC 2616: PUT vs POST URI structure

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

Josip Miskovic
About Josip

Josip Miskovic is a software developer at Americaneagle.com. Josip has 10+ years in experience in developing web applications, mobile apps, and games.

Read more posts →
Published on:
Download Free Software Developer Career Guide

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.