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.

PUT /article/1234 HTTP/1.1
<article>
    <title>red stapler</title>
    <price currency="eur">12.50</price>
</article>
POST /articles HTTP/1.1
<article>
    <title>blue stapler</title>
    <price currency="eur">7.50</price>
</article>

HTTP/1.1 201 Created
Location: /articles/63636

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:

PUT /articles/green-stapler HTTP/1.1
<article>
    <title>green stapler</title>
    <price currency="eur">9.95</price>
</article>

HTTP/1.1 201 Created
Location: /articles/green-stapler

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.

See also