While this is clearly not REST-ful, the fact that the comments here can spend so many words philosophizing over whether this ought to be PUT vs. POST vs. PATCH illustrates why REST is not my favorite technology.
It's like XML all over again. Should it be an attribute or a child node? Should the parameter go in the header, or in the body, or in the URL? Should it be part of the URL path, or a URL parameter? Should the error be indicated in the HTTP status code or just in the body? Did we get it right, or do we need to find a Roy Fielding quotation illustrating the principle we violated?
Normally this wouldn't bother me, since I generally have faith that the "free market", so-to-speak, will favor the best technologies in the long run. But HTTP and REST have an artificial boost in that they are the only way to get through many firewalls, so in essence everyone has to go along with REST whether they want to or not (or at least tunnel over it). And of course everything can be made to work with REST, so everyone eventually converges on it, even if it's not the best fit, and its dominance grows.
Some of this is pedantic. But mostly, it's calling out, without much grace, that this API is a failure of a design. Not because it's not [insert buzzword] but because:
1. what happens if you visit a control panel page in chrome? Does chrome spider ahead, eagerly caching the links on the page assuming that visiting a page has no side effects? Have fun silencing your horn and windshield wipers from simply visiting your control page.
2. what happens if chrome then has that "get" url very strongly cached? After spending 10 minutes trying to silence your car from your first visit to the page, the "honk horn" button now does nothing but load the word "true" from the browser cache.
3. what if any of the above happens while you are on the road ? what if some wise guy down the line decides that a car should be designed API first, and your dashboard, pedals and wheel are just one of many potential API clients? Can you really now tolerate using the GET method in ways that it is explicitly documented to not be used?
This isn't just philosophical or quibbling over definitions. Getting this wrong means things actually break in the real world.
Will the browser cache XMLHTTPRequest GET requests? I hadn't realized it would do that.
I agree that if anything between you and the server is going to cache requests then you need well-specified behavior around that. But that particular problem can be solved by a specification much, much simpler than all of HTTP.
I also see that it's useful to know that certain requests will not be state-changing for purposes of pre-fetch. But while I agree this is important for the browser, I question how important it is for APIs. API calls are usually constructed programmatically -- V8 isn't going to start just randomly guessing what XMLHTTPRequests you might come up with next and start fetching them. This is where I think that browser-based paradigms with a human user diverge from programmatic ones.
It costs nothing to switch those GETs to POSTs (or fucking whatever method best describes the kind of side effect you're doing). why are we making excuses for doing the obviously wrong thing?
I get what you're saying about the API… but if you're going over HTTP why not play by HTTPs rules. Presumably it's an app that is the primary consumer of the API so they could use any sort of protocol. Why decide to use HTTP but not conform to the standard in a way that ruins any benefit you might have got out of using HTTP instead of say:: OSC or.. basically anything OTHER than http would be better.
If we're talking about using HTTP to bust through a firewall, then that stuff is DEFINITELY going to break unless you use HTTP in as dull and ordinary a way as possible, and GET requests will always be cached by god knows how many different machines between you and the car.
If it's not an app, then we've decided to put a webserver on the car so that we can serve a website with some javascript that does XHR calls to make things happen. I would not put it past google to make a future version of chrome that prefetches JSON api requests. But regardless, yes, XHR calls do go via the browser cache. and the proxy cache. and the firewall. and any other machine that makes basic assumptions about what those methods mean.
> why are we making excuses for doing the obviously wrong thing?
Sorry if I was unclear -- I wasn't advocating a mis-designed API, I am suggesting that HTTP is way more complicated and subtle than it needs to be for the purposes of remote APIs.
I concede that providing enough information to know what is cacheable (and what the caching key is, etc) is justified complexity. But I think that the other 95% of semantics that "pure" REST demands you follow are pretty useless and pedantic.
YES! (though I'd quibble with s/sometimes/usually/)
To reply to my siblings:
HTTP is in practice a great transport protocol, because of the world we live in. That's an affront to ivory tower engineering (my favorite kind), but it's a lot better than failure to ship (or shipping something that only works under non-existent conditions).
And RPC needs some kind of container protocol, and SOAP is one possibility, sure. Keep it the hell away from ME, but it's one option. The sane option is to do just what all these so-called RESTful services actually do (modulo not using GET when you should POST), with pleasant-but-not-dogmatic URIs, and JSON, and so forth, and just stop calling it REST, because it's not REST at all. Or call it whatever you like, but get used to endless trolling from pedants like me.
Aside from the bad HTTP verb choice, isn't TFA a pretty reasonable API implementation?
Of course, as sillysaurus noted.... TFA doesn't call it RESTful at all... that was just the HN headline. Oh how we've been trolled.
If the only flaw here is the mis-use of the term "REST", I'd say it could be worse: they could actually try to make it a RESTful API!
I too am not very fond of REST, but for slightly different reasons. While I acknowledge its benefits, I'm afraid REST will go the way of OOP in terms of fad-chasing, resulting in massively over-architected and contrived systems.
I went through that madness when trying to figure out Hypermedia APIs. Supposedly you're not RESTful without hypermedia, but the whole thing seems crazy when you get into it.
Perhaps, just as JSON became a more functional and popular format than XML we can build a new REST spec that simplifies all this.
I (really do) hate posting this but I swear every single "REST" or "RESTful" or "REST-ful" API post I see, there's always that guy that chides it for not being pure or REST or "-ful" or something. Do we really care that much? Does the API work? If so, move on...
The main issue with the quoted example is that GET is intended for non-destructive interaction with no side-effects. Whether you use PUT or POST is a much smaller argument than whether to use GET or something else.
To most people, honking the car's horn is an unwanted side effect.
As has already been pointed out, some browsers will fetch-ahead to ensure that pages appear to load instantly. If you open a page which is a bunch of buttons which do stuff like honk the horn, lock the door, raise the window or open the charging port door, there will be unwanted side effects.
If it doesn't follow the design pattern in some form that it states it does, then it should be referred to as the technological interface it's offered through - in this case a web service.
I would love an answer for this. How can we describe an api without just calling it a generic 'web service' - where that may be misinterpreted as being a SOAP web service. And it's not strictly a REST web service.
It's like XML all over again. Should it be an attribute or a child node? Should the parameter go in the header, or in the body, or in the URL? Should it be part of the URL path, or a URL parameter? Should the error be indicated in the HTTP status code or just in the body? Did we get it right, or do we need to find a Roy Fielding quotation illustrating the principle we violated?
Normally this wouldn't bother me, since I generally have faith that the "free market", so-to-speak, will favor the best technologies in the long run. But HTTP and REST have an artificial boost in that they are the only way to get through many firewalls, so in essence everyone has to go along with REST whether they want to or not (or at least tunnel over it). And of course everything can be made to work with REST, so everyone eventually converges on it, even if it's not the best fit, and its dominance grows.