I said what I said, and I mean every word of it.
Rewind
For those a little confused, let's back up.
REST (REpresentation State Transfer) APIs are still very common, and honestly I don't have an issue with them for most projects. REST APIs work by using HTTP verbs to denote the purpose of a request, i.e. a GET request on a given endpoint (say "comments") means that the user is trying to get a list of (or perhaps a specific) comment value(s). DELETE along with an identifier of some type does just what you think it would: removes the resource given by the identifier. The last two main HTTP methods utilized with REST are POST and PUT, and this is where I seem to break with most API designers / REST routing libraries.
Schism
The last two, in English, are very close to one another due to some extra uses of the word "post", as in to "post a job listing" (i.e. put up, create). For a long time many back-end languages didn't have good support for requests outside of GET or POST (for reasons I honestly don't know), so POST sort of fell as the default for anything that needed more security in sending data (i.e. not transmissible through the URL).
With the growth of AJAX (i.e. XMLHttpRequests) REST APIs became the flavor-of-the-month and with it developers should have thought about our default to using POST requests for creating data / records. Not many did, unfortunately, and many places that use REST APIs have, in my opinion, mixed up PUT and POST.
My Argument
I read an article some years ago (if I can find it I will link it, but so far have been unsuccessful) stating that the four big verbs (GET,DELETE,PUT, POST) are really the only verbs you'd need for a large majority of use cases. In that post the author made a point: POST requests are (in his opinion) for resources that are being modified, not created, because they are POST creation. To create new values, you would PUT data to the server (database).
I think PUT has always made more sense as the verb for adding new data, but please give me any reasons you may have for thinking that POST is the preferred method.
Top comments (6)
In my opinion, I think that everything should stay the way it is. Not that your argument is not valid, but that it doesn't post enough incentive for REST API's to change their HTTP methods.
I'm just saying, "If it ain't broke, don't fix it."
No hate though, love this post! It was a really good topic to question.
Thanks for the reply, I generally don't get any!
I agree, there really isn't an incentive to change -- plenty of people have plenty of code that uses the most popular system. But I think we both know that sometimes "if it ain't broke..." usually just delays the big bugs in the programming world. Not that I know what would possibly break from current implementations, just that I've seen that happen so often (I mean... hasn't every developer?) that I'm assuming something is going to happen eventually. It's just something I felt like I needed to get off my chest.
Oh yeah of course! Some things get to the point where it's not really broken, but so inefficient that it's practically broken. Even though HTTP requests are at that point, definitely a valid point.
I think the importance of the methods name is the convention, the fact that everyone agree on its meaning, semantic correctness goes second in this case; even if your argument is semantically correct it goes against the convention. We have to ask ourselves the cost/benefit of adopting a new approach, in this case the benefit is that is arguably semantically correct (I don't agree, more on that below), the cost is that will confuse the API consumers maybe even generating problems, for me, not worth it. And because is a convention, to avoid confusion almost everyone would have to adopt the change immediately, the longer the change take, more confusion.
I don't agree in the semantic mean of POST, I don't think it refers to later or after, PUT is not PRE after all, POST refers to the verb, the act of posting; we have to consider that the methods are verbs, the use of POST as "after" is not a verb, is a prefix, that mess up everything. Pigs would start to fly, sky would turn green, gravity would turn the other way and earth would actually go flat and hollow.
Well, "POSTing" is simply a synonym for "PUTting up". Like I said, the two words get muddled because English.
If we want to be more technically correct, then really the argument becomes about the poor and forgotten
PATCHverb, which I think is more technically in line with updating a resource. The issue is further compounded by the fact that you get slightly different language aboutPUT,POSTandPATCHwhich muddle the meaning around them.I agree that convention is largely useful, but sometimes the convention can (and should) be put into question. We can hold no things to be holy, simply because we are told that they are.
POST is like posting an article in a paper, usually don't include the pk in DB, that depends on the implementation on said DB. Is a POST request, in this case the location is not part of the request is up to the receiver of said request.
PUT is the act of just put it there, when you PUT something in some place, location is in fact relevant, putting your hand in the hand of other to greet is very location sensitive, your hand should be in the others hand nowhere else. So the location should be included in the request, the receiver should refuse if the location requested is not available. In case of a DB if the requested pk is already taken or invalid. Is a request to add an entire entry.
PATCH should modify data a registry already in the DB, is for partial modifications of an entry, is different from PUT in that. To use PUT to update is against the convention.
That's how I understand it and makes sense to me, also, language is not always (ironically) literal in the strict sense; CPU is arguably not a unit, container and VM are very abstract and what about cookies, browsers, database, boot, uptime, etc. Technology is too fast, we end up reusing words not designed for it, as I said is a trade off, we should be making new words for new concepts; a screw is not called "rotating nail" nor hammers "heavy things with handles" after all, but imagine the extra mental load to learn thousands of technical new unrelated sets of letters for everything new. The web is not actually a web as we understood it a century ago.