PUT vs POST

The question comes up in interviews and when you design an API. The meaning of the methods is defined in RFC 9110, HTTP Semantics; an API can still use them its own way, so the documentation of a given API has the last word.

The short answer

PUT puts the sent data at the URL of the request: it creates the resource there or replaces it completely. Sending the same PUT twice leaves the same state as sending it once.

POST hands the sent data to the resource at the URL, and that resource decides what to do with it. Most often it creates a new item and the server chooses its address. Sending the same POST twice can create two items.

Who chooses the URL

With PUT the client knows the final address:

curl -X PUT -H 'Content-Type: application/json' -d '{"name": "Rex", "status": "available"}' https://api.example.com/pets/42

With POST the client sends to a collection, and the server answers with the address it gave the new item, usually as 201 Created with a Location header:

curl -i -X POST -H 'Content-Type: application/json' -d '{"name": "Rex", "status": "available"}' https://api.example.com/pets

The codes are explained in HTTP status codes.

Idempotence

A method is idempotent when several identical requests have the same effect on the server as one. PUT, DELETE and of course GET are idempotent, POST is not. This matters on a bad network: a client may safely repeat a PUT whose answer got lost, but a repeated POST may order the same goods twice.

Both have a body

A common myth says that PUT puts everything into the URL and has no body. It is the other way round: the body of a PUT is the new state of the resource. Both PUT and POST normally carry a body, in JSON, a form or any other format. For GET, HEAD and DELETE a body has no defined meaning, and servers may ignore or reject it.

An example: Swagger Petstore

The sample API of the Swagger Editor shows both styles. POST /pet adds a new pet, PUT /pet updates an existing one:

Further down, POST /pet/{petId} updates a pet with form data. So POST can update too; it is the resource that decides what a POST does:

PATCH

PUT replaces the whole resource: fields left out of the body are gone afterwards, or set to their defaults. To change one field, APIs use PATCH, which sends only the changes:

curl -X PATCH -H 'Content-Type: application/json' -d '{"status": "sold"}' https://api.example.com/pets/42

In an interview

• PUT creates or replaces the resource at the given URL; POST sends data to a resource that processes it, usually creating a new item at an address the server chooses.
• PUT is idempotent, POST is not.
• Both carry a body.
• What a given API does is in its documentation; check before you assume.

To try the methods yourself, see API testing. To see a request as plain text on the wire, type it by hand over telnet.

Article authors: Andrei Olegovich, Klavdiya Kondakova