I've written probably half a dozen unrelated apps that call REST APIs and I think they all implemented REST differently. Some treat PUT as insert while POST as update. Some treat POST as insert, PUT as insert/update. Some return 201 when insert was successful, some return 200 whenever anything is successful. Some issue tokens, some authenticate using headers.
The problem with people trying to be RESTful is that they pay too much attention to stuff that doesn't matter (71 status codes) instead of stuff that really matters (simplify complex insert/update). I'd rather have Trello return 400 on errors and provide a text description than use one of the 30+ 4xx errors. And I'd rather have them accept due date when inserting a card. Trying to conform to REST's standards is like trying to be XHTML compliant. Great, your site validates. But you're still using white font on yellow background!
Be as RESTful as you need to be. But more than that, be useful and sensible. Don't make me call your server six times to make one valid GET request.
"POST is insert - PUT is update" is the norm and HTTP compliant way of doing things. Why not reach out to Trello and ask why you can't do the due-date on POST?
Unfortunately, I don't think the POST vs. PUT distinction is quite that simple - PUT is often used to create/insert if you are sending all the data required to create the new object as part of the request.
NB Personally I thought this use of PUT was splitting hairs when I first started reading about RESTful interfaces but having used a few and written one RESTful service it does rather make sense.
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.
unless you're the one maintaining the api and the calling code doesn't/won't/can't distinguish between insert and update because the de-dupe algorithms are not up to snuff or the current financial year doesn't have budget to get the third party feeding your api to re-develop it.....
Just last night I wrote some code to auto-create Trello cards and assign them to a specific list. The https://trello.com/docs/ seem fairly decent but what they don't tell you is that POST is insert, PUT is update. Moreover, while you can assign a due date via PUT ( https://trello.com/docs/api/card/index.html#put-1-cards-card... ), you cannot assign one via POST ( https://trello.com/docs/api/card/index.html#post-1-cards ). So if you want to create a card with a due date, you have to POST, read ID, then PUT the due date to /card/id.
The problem with people trying to be RESTful is that they pay too much attention to stuff that doesn't matter (71 status codes) instead of stuff that really matters (simplify complex insert/update). I'd rather have Trello return 400 on errors and provide a text description than use one of the 30+ 4xx errors. And I'd rather have them accept due date when inserting a card. Trying to conform to REST's standards is like trying to be XHTML compliant. Great, your site validates. But you're still using white font on yellow background!
Be as RESTful as you need to be. But more than that, be useful and sensible. Don't make me call your server six times to make one valid GET request.