PUT should be idempotent and addressed at the location of the resource to be created / updated. e.g /books/[isbn], while POST should be addressed at the location of the collection and give the location of the new resource or an error. e.g. POST to /books to create a new book entry.
That's still an oversimplification. POST only implies that the request is NOT idempotent, and that the request body is submitted to the origin server for "processing". Consider for example, resources that search for other resources via information in the request body and redirect to them. There's nothing wrong with this pattern, and in fact it works nicely for rapidly-changing server-side information since caching the result of a POST is not allowed.
The core problem in my mind, is not whether one should insert or update on PUT/POST, but whether one should even be considering HTTP-based APIs to be gateways to what amounts to a database. The domain concepts in the application might not map directly to a resource-centric design, and that's ok. When you focus on the resources, their behavior, and hypermedia, then you "get" REST. If your application isn't shaped like HTTP/REST, then maybe it shouldn't try to be.
> The core problem in my mind, is not whether one should insert or update on PUT/POST, but whether one should even be considering HTTP-based APIs to be gateways to what amounts to a database.
I think it's widely recognized that you shouldn't consider making your REST API a direct gateway to a database. For one, it's potentially very dangerous, but it is also limiting the design of your API, because typical databases basically have no way to insert anything besides rows of data with fixed columns (relational) or raw untyped data (NoSQL).
I think the 'purest' form of REST API's for creating and updating is that PUT should be idempotent and used for existing resources addressed by an existing URI, while POST can basically create resources any way it sees fit, and return the URI of the new resource. This allows doing a POST followed by a PUT to create and initialize a resource, without having to know how and where the resource will be created, and without requiring to set each and every attribute of the resource with the POST request.
Exactly, that's why the POST/PUT distinction makes perfect sense when you actually write code but seems a bit academic when you read most descriptions of how RESTful interfaces should work.
