Intuition

Think as:

1
2
PUT = insert or update;
POST = insert

So when you make 2 PUT - you get the one new record; when you do 2 POSTs - you get 2 new records.

False

Neither of the following is right:

  1. POST used to create, PUT modify;
  2. PUT used to create, POST modify;

Better

Choose between PUT and POST based on idempotence of the action.

PUT implies putting a resource - completely replacing whatever is available at the given URL with a different thing. By definition, a PUT is idempotent. “Do it as many times as you want, and get the same result”. x=5 is idempotent. You can PUT a resource whether it previously exists, or not.(e.g. to update, or create).

POST: updates a resource, adds a subsidiary, or causes a change. A POST is not idempotent, in the way that x++ is not idempotent.

1
2
x = 5 // PUT, idempotent
x++  // POST, not idempotent

By this argument, PUT is used to create when you know the URL of the thing you will create. POST can be used to create when you know the URL of the “factory” or manager for the category of things you want to create.

e.g.

1
POST /expense-report

or:

1
PUT /expense-report/10929

In the sense that only “this” ONE kind of expense-report. For a specific existing instance of report, only update it, do not re-create a second instance: PUT.

For the above POST, if POST many times, many kinds of reports are created, even though they are completely the same: POST can be idempotent, but also may not be. Hence, POST is not idempotent.

for more info, see original post