When should we use PUT and when should we use POST?
The HTTP methods [POST] and [PUT] aren't the HTTP equivalent of the CRUD's create and update. They both serve a different purpose. It's quite possible, valid and even preferred in some occasions, to use [PUT] to create resources, or use [POST] to update resources.
Use [PUT] when you can update a resource completely through a specific resource. For instance, if you know that an article resides at http://example.org/article/1234, you can [PUT] a new resource representation of this article directly through a [PUT] on this URL.
If you do not know the actual resource location, for instance, when you add a new article, but do not have any idea where to store it, you can [POST] it to an URL, and let the server decide the actual URL.
As soon as you know the new resource location, you can use [PUT] again to do updates to the blue stapler article. But as said before: you CAN add new resources through [PUT] as well. The next example is perfectly valid if your API provides this functionality:
Here, the client decided on the actual resource URL.
Caveats
- [PUT] and [POST] are both unsafe methods. However, [PUT] is idempotent, while [POST] is not.