So far we have learned that we are using PUT to update a resource, and POST to create a resource, but it is true that even though PUT updates, both are able to be used to create new data.
Let me explain, a PUT request will be sent to the server, for being this type of request, the server will check if the data exists, if it does it will be updated, if it doesn’t it will be created.
Then why do we have POST, first let’s get tangled a little more, because POSTs requests can also be used to update data, that said, we have both for one main reason: idempotency. What is that? It is the capacity of an operation to be called multiple times without changing the outcome more than once, a PUT request is idempotent so it will not create or update multiple times the same item, whereas POST would.
for example: PUT /expressions/1?name='bob'
if the server encountered a problem reaching the endpoint(not related to the request), it would try again, for put, it means that if in one of those cases the changes went through, it will not do the update again. Yet, if it was a post request: POST /expressions/1/?name='bob'
It means that if the same issue happens it might rewrite over and over again each time it tries, and even cause either an overload error or at least spend more running time.
Why would we use POST, then?
Well, being not idempotent can also mean that between the two it is a safer route to create an item with sensitive data because the request is not cached (which is a way of storing information temporarily).
This is why we learn at Codecademy that is good practice to implement POST request for creation and PUT requests for updates, but it is also good to know what else they can do, why, and why we wouldn’t use them that way some times.
Some statements made by @axelkaban are wrong. I will try to explain what is going on.
When we are talking about the design of APIs we are always talking about conventions. There are no hard rules to follow. And in REST the convention is to use the POST method to create new resources and PUT method to modify existing resources. That is why I would not state that these methods are interchangeable in REST. If you don’t want to follow REST guidelines you can even create new resources via DELETE requests, but your clients probably would not be happy with this choice
To emphasize this point, let’s take a quick look at GraphQL - a runtime for fulfilling queries with existing data stores that is gaining popularity in the last years. GraphQL uses a different approach - it only uses GET and POST methods to execute all sorts of operations - reading, creating, modifying, deleting etc.
Convention, nothing more.
The server returns error 5XX if any problem is encountered Simply try to forget this part, it’s wrong.
We have to explain what idempotency is. As I explained earlier, we are talking here about REST API. In REST method PUT is idempotent, method POST is not. Let me explain why. This is how POST request usually looks like:
This request will create a new book record using data sent in the request body (name of the book, name of the author, publication date…).
Let’s say that I sent this request and accidentally I pushed the button one more time - the second request was sent. What happens now? The second request will create a new book record with exactly the same data (if I do not make any special validation on the server-side).
This is why the POST method is not idempotent by convention. In the case of duplicated requests - each request will make changes in our data store.
Now let’s take a look at the PUT method. Usually PUT request looks like this:
This request will modify book record with id 12 by replacing existing data with the data sent in the body of the request. But if this resource (book with id 12) does not exist then this record will be created.
The same situation again, I sent the request and accidentally I sent the duplicated request. What happens? The first request will modify existing resource or create a new one and the second request will not make any difference (book with id 12 already exists and it has the same data as the one sent in this request). This is what makes PUT idempotent by convention.
Idempotency is not related to caching. In REST we use term safe method to describe methods that are safe to cache, but this is not strictly related to idempotency.
I stubbornly used words idempotent by convention. I would like to explain why. DELETE method is by convention idempotent, just like PUT, because this is how usually DELETE request looks like:
So if there are 2, 3, 4, 5, …, 19 duplicated requests it does not matter - this resource was deleted by the first request.
But sometimes, API creators decide to expose this kind of endpoint:
This request will delete the last added book. And now, is this method idempotent? Three duplicated requests will result in the deletion of three resources, so the answer is no.