This is often an item for debate when making a new API: when should we use PUT and POST verbs in HTTP? how do they differ?
You may have heard 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 oversimplification. PUT can be used for creating a resource as well as updating. POST always creates a new resource. Both verbs will be explained below, starting with PUT.
What is the PUT Verb
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'
}
In the above we see there is a natural key, the Id (ISBN). A major difference between PUT and POST, is that with PUT, If we make the above request again and again we end up with the same result. The first request creates the resource with '978-0201616224' and the subsequent requests replaces 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.
What is the POST Verb
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 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. You could also say that PUT is for when the client should create the id and POST is for when the server should.
If you found this POST helpful, please let me know in the comments down below!