Why do REST verbs not necessarily correspond to CRUD actions?

Question

I sat in a talk from Eric Evans (author of Domain Driven Design) and he made the point that it was a confusion of REST to assume that the four REST actions automatically mapped to the four CRUD actions. ie

POST   x=> Create
GET    x=> Read
PUT    x=> Update
DELETE x=> Delete

I kind of missed his reasoning. Something about the architectural concerns being different.

My question is: Why do REST actions not correspond to CRUD actions?

Answer 1

Because of Idempotence

POST and PUT can both be used for "create" and "update" operations. The difference between POST and PUT is idempotence: PUT is idempotent, while POST is not.

Idempotence is the property of certain operations ..., that can be applied multiple times without changing the result beyond the initial application.

• Wikipedia

This means that in order to comply with the HTTP specification, you must use PUT for idempotent operations and POST for non-idempotent ones. This is specified in RFC7231 section 4.2.2.

Note that idempotence is described by the HTTP standard and has nothing to do with REST directly.

Example

Understanding idempotence is easy with an example. Let's take a create operation on a REST API that should create a "customer" resource. The idempotent variant would look as follows:

PUT /customers/cust42
{ "name": "John Doe" }

This creates the customer with name "John Doe" with the ID "cust42". The important part here is that the client specifies the ID. If the client issues the same PUT request again, no new resource will be created - the operation is idempotent.

With POST, on the other hand, the request would look as follows:

POST /customers
{ "name": "John Doe" } 

The server determines the ID and creates a customer resource with name "John Doe". This operation is not idempotent, because issuing the same POST again would create a second user resource.

So choosing between POST or PUT is not a question of "create" vs "update". The above examples both create a resource, but one does so in an idempotent manner (PUT) and the other not (POST).

Relation to DDD

In DDD, the goal is to create a language around your domain problem in a way that is meaningful to the domain (and their experts). Naming everything after CRUD is thus generally a bad idea.

The above guidance is still useful, for DDD, however. If you have state-changing API operation on your DDD application that is idempotent, you use PUT, otherwise you use POST. See the answer of Guillaume31 for some good domain-oriented examples of DELETE.