PUT vs POST: What's the difference?

Difference between POST and PUT methods

The key difference between PUT and POST methods is that a PUT is restricted to create or update operations, while a POST operation may perform any type of processing. Unlike a POST, PUT operations may only operate on the resource identified by the URL provided. HTTP POST processing is allowed on any server-side resource, regardless of the URL.

POST operations should give preference to resources subordinate to the resource identified by the URL. RESTful APIs and operations should be predictable in how they manipulate the resources and generate results.

HTTP PUT method example

Imagine a flight tracking system with which users look up the status of American Airlines flight 123 at the following URL:

www.example.com/AA123

To update flight AA123’s status, a web service performs a PUT operation to that URL.

The PUT operation includes a JSON or XML payload that fully describes the new status:

PUT URL: www.example.com/flights/AA123
PAYLOAD: {"status":"ontime", "gate":"b12"}

HTTP PUT create example

Now, imagine we need to create a new entry for Air Canada flight 789.

A URL that describes this flight does not exist yet, but we know that after creation the URL will be:

www.example.com/AC789

Since we know the desired URL of the resource before requesting its creation, we must use a PUT operation.

PUT URL: www.example.com/flights/AC789
PAYLOAD: {"status":"late", "gate":"c17"}

HTTP POST method example

When a client requests creation of a resource, it doesn’t always know what URL the server will assign to the resource.

When one uses the POST operation is used to create a resource on the server, the resource is created as a subordinate resource to the URL that the POST operation provides. This places HTTP PUT vs. POST methods in stark contrast, as the PUT operation requires the exact URL of the resource to be created or updated.

Not knowing the exact URL of a resource prior to its creation is a common scenario in database driven applications where a newly created resource is identified by a value that’s generated after the resource’s data is written to a table.

Primary key-based identifiers fall into this category.

If you need to create a resource that is subordinate to the URL provided, you should use a POST method, not an HTTP PUT method.

For example, to create a new customer, a RESTful microservice uses the HTTP protocol’s POST method. All of the information needed to create the new customer is provided as JSON or XML in the request’s payload:

POST URL: www.example.com/customers
PAYLOAD: {"name":"Joe", "age":"29", "city":"ajax"}

HTTP POST create example

When the server completes this request, it creates a new URL that uniquely identifies the new resource.

The following example shows a possible URL generated by a database-driven application for this new customer after a successful POST operation:

www.example.com/customers/j567

When a POST operation creates a new URL, REST demands that the new URL is sent back to the calling program as a location header. This allows the calling program to use PUT operations for future updates.

This is why the difference between a PUT and POST operation is often phrased as: To create an object, use a POST. PUT should be used for updates. That’s an oversimplification of the purpose of the HTTP verbs, and by no means should you map HTTP methods onto SQL-based CRUD operations. Nevertheless, as a high-level simplification, it’s allowable.

POST and PUT idempotence

One rule the HTTP protocol places on PUT operations is that they must be idempotent. Idempotency has never been a requirement of POST operations.

To be idempotent, an operation could be invoked once or 100 times and the result on the server would be the same.

Idempotence example for PUT and POST methods

For example, I perform a PUT operation to set my bank account balance to $100. Even if I perform that operation 100 times, the end result is a balance of $100.

In contrast, if I perform 100 POST operations that each increases my account balance by 10%, the result of each interaction creates a different result. That is not an idempotent operation.

A PUT method allows only idempotent operations. POST methods are not subject to idempotency requirements.

PUT is idempotent. POST is not.

Should I use PUT or POST?

The HTTP specification RFC 7231 is very clear that the PUT method is only used to perform idempotent create or update operations:

The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload.

In contrast to the PUT, POST operations are not limited to creates and updates. That HTTP specification also says that upon receiving a POST invocation, the server may choose and implement any logic to support the request:

The POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics.

This is why many RESTful APIs extensively use the HTTP protocol’s POST method. If a function or service doesn’t map neatly onto one of the HTTP protocol’s GET, PUT, PATCH or DELETE methods, the POST method gets used.

When software architects build and design a RESTful API, it is important for them to respect the manner in which to use the various methods of the HTTP protocol. That includes knowing the difference between when to use a HTTP PUT vs POST operation.

PUT, POST, GET and DELETE

The first version of the Hypertext Transfer Protocol only supported three HTTP request methods: GET, POST and HEAD.

• The HTTP GET method simply retrieves requested resources.
• The HEAD operation just gets headers and metadata about a resource.

So, in the original HTTP specification, any server-side processing of data was performed by a POST. That included:

• Resource creation.
• Resource deletion.
• Updating resources.
• Data processing.

Updated versions of the HTTP protocol have added methods including the following:

• DELETE for deletions.
• PATCH for updates.
• PUT for resource creation or replacement.

These additional HTTP methods provide clarity and reduce the scope of duties associated with the HTTP POST method. The evolution of the HTTP protocol also explains why any request that does not neatly fit into a DELETE, PATCH or PUT operation falls into the domain of the POST. Unlike PUT, POST is the catch-all method of the HTTP protocol.

There are 9 commonly accepted HTTP methods including PUT and POST.