Put VS Post - when to use what for web and REST?

I often hear this discussed: when should we use PUT and POST verbs in HTTP? how do they differ? and are they not very closely related? (the same)

I sometimes see the definition that PUT is for updating and POST is for creation. Even though PUT can be used for updating and POST for creation, it is an over simplification. PUT can be used for creating a resource as well as updating. POST always creates a new resource.

PUT

When using PUT the client provides the Id of the resource they want to interact with. If they make a put on an endpoint, the request will contain an Id. If we use the example of updating information on books and have the endpoint we could put the following JSON object:

{
   Id: '978-0201616224',
   Title: 'The Pragmatic programmer'
}

Here there is a natural key, the Id (ISBN). Here is the major difference between PUT and POST. If I make the above request again and again I end up with the same result using PUT. The first request creates the resource with '978-0201616224' and the subsequent requests updates it. Since all the requests are the same, the updates "do nothing". This is due to the idempotent nature of PUT.

If you were to change the title of the book in the API, you would assume that it is updated when called with a different title. like the following:

{
   Id: '978-0201616224',
   Title: 'The Pragmatic programmer 2'
}

This of course depends on the implementation behind the endpoint, but the idea is that you can use the same endpoint to update the resource.

POST

Using POST you would not have the unique id as part of the API. The request would only contain the Title:

{
   Title: 'The Pragmatic programmer'
}

This also means that if you make several requests, you will make that many creations of the book with the Title "The Pragmatic programmer". This is also the reason why many have started to use PUT instead of POST. Most of the time you do not want to create several resources with the same content. Have you ever made a request that timed out and wondered if it actually made it through? This you do not have to worry about when you use PUT, you just make the request again. This is a huge advantage.

When to use POST

  • When you need to create a resource
  • Sending the same POST request twice will create two instances
  • No specific resource is specified in the URL (like /books)

When to use PUT

  • Creating or updating a specific resource
  • Sending the same PUT request twice creates and then updates the resource (nothing happens as it is the same values given for the resource)
  • A specific resource is targeted in the URL (like /books/1)

Something important to remember is that, you do not need to support both! You should choose the verb used depending on what you intend to do. If the user provides the Id for the resource they are creating - or has it - use PUT. PUT has the advantage of being idempotent. POST is great for comments, where the user basically attaches a piece of text to a resource. There is no natural Id here, then again a Id can be added to make the request idempotent. This is one of the reasons why many implement PUT instead of POST these days.

If you found this POST helpful, please let me know in the comments down below!