And right there, at your final sentence, you basically described why REST has more or less failed.
GET and POST are useless for implementing a complete application protocol. You'd basically overload these http verbs to the point where you would implement your own protocol. And that's what most people do anyway. You choose to not use PUT, some other person chooses to not use PATCH or HEAD and I choose to curse vehemently every time I have to use someone's service.
REST is nothing but loosely connected guidelines that nobody uses in the same manner.
Could things be better? No doubt. But REST (or something like it) is largely "the way things are built" these days and most people don't mind. Calling it a failure is quite a stretch IMO.
How many browsers do you have? 3-5?
How many REST client libraries are there?
Answer: one per service(per programming language).
What kind of protocol is that?
OK, I get what you're saying. Problem is that as far as I can see REST is perfect for S3-like services, Maps(?) and slightly more than basic CRUD applications.
You are bound to discover its limits very soon. The gazillions of books and blogposts out there heralding it as a serious interface are not helping either.
BTW, I don't know about other people criticizing, I am definitely not a purist. But after ~10 years of dealing with REST in various capacities(startups to Enterprises), I am a bit tired and can't wait for something to replace it.
The REST API I had to forward through however had no good documentation, no client library, so I was forced to write json serializers and reverse engineer the code. Overall, when you have a well written SOAP interface (rare, admitted), development time can be greatly reduced.
I learned SOAP relatively recently, but well after it was a fad. Today, my experience would be like yours if I had to make a SOAP service with just a WSDL. But when I started out? It would take a longer for me to wrap my head around all of it. I can't imagine how confusing it would be if I had to do it all without the benefit of working on a team whose focus is a SOAP-based product. I dunno if I would know where to begin.
Compare that to REST. Even if you know next-to-nothing to start, you can do a basic REST tutorial for just about any stack in an hour, and get a basic implementation of an API up in an afternoon.
Also, you don't seem to have looked terribly hard, because there are a few really powerful tools out there for autogenerating server and client code for REST APIs, as well as mock servers and a whole host of other tooling (See: Swagger, RAML, API Blueprint for starting points).
I've used a variety of tools to generate and test REST interfaces in the last ten years. To a mixed success, I must say.
I don't see a problem with this. In fact, I'd love it if everyone accepted this instead of whining that something isn't truly "RESTful."
For instance, the app I'm working on deliberately does not implement HATEOAS. I appreciate the academic effort behind REST and RESTfulness, but ultimately I view it only as an ideal to tend toward. As you said, it's a guideline.
GET and POST are all you need: "Return representation of available operations" and "apply this operation". It's the lambda calculus applied to the web (see Waterken's web-calculus for a more formal treatment).
You might say that this is too anemic a foundation and you want more built into the protocol level to handle some common tasks, but I'm not convinced it's necessary or even desirable. At some point requirements will change and some of those tasks will be supplanted, but we'll have to live with them forever if we bake it into the protocol.
I can do you one better. If you managed to reduce everything down to GET and POST here's an idea; just use POST for everything. Boom. You just re-invented SOAP.
How? Perhaps you should actually elaborate your argument. REST doesn't depend on the use of verbs, it's an architecture that elaborates the requirements for object designation (URLs), object lifetimes (statelessness) and hypermedia-driven service discovery (HATEOAS). Only GET and POST in HTTP are required to fulfill these requirements. If there's actually something wrong with that, then lay it out.
> If you managed to reduce everything down to GET and POST here's an idea; just use POST for everything. Boom. You just re-invented SOAP
Except you can't in a world with side-effects. You could do exactly what you say if every POST were guaranteed to be idempotent. Every request could carry a full payload like a POST request and a unique identifier to ensure at-most-once semantics. That would be a fine protocol, and totally REST compatible. What's the problem exactly?
Finally, SOAP carries far more baggage than you imply. It's a false equivalency.
When you encapsulate most of your operations under POST you basically create your arbitrary protocol. No assumptions can be made about your service. You can make your own assumptions about your own service, but the others can't.
> That would be a fine protocol, and totally REST compatible. What's the problem exactly?
The problem would be that it wouldn't be REST compatible. You should clearly read a few books on the subject. Friendly advice, not a snarky comment.
REST already has idempotent mutating operations, like PUT and DELETE. It's not just GET that's idempotent. So clearly the problem is that you redefine your own protocol, with your own semantics, even though we already have plenty of standardized methods/response codes.
> If there's actually something wrong with that, then lay it out.
You have obviously missed a ton of bibliography on the subject. Before reading random blog posts from random people who have their arbitrary assumptions about what REST is, I'd suggest reading a few books on the subject.
Honestly sorry if I sound snarky, but after 10 years on working with such APIs, and after reading countless books on the subject, it never ceases to amaze me how people still think that GET and POST are enough. But I don't blame you, but the browsers who basically broke the protocol by just using those 2.
And you shouldn't make such assumptions, you should just use the input parameters exposed in hypermedia which you obtained from a public service entry point. It's called encapsulation and that's REST. Again, what's the problem? All I hear is complaining that REST doesn't work the way other architectures work. Big surprise.
Certainly REST's HATEOAS can sometimes make a service less efficient as compared to some alternatives (so it can preserve encapsulation and support upgrade), but that's not the claim you're making. You're claiming some kind of insufficiency.
> The problem would be that it wouldn't be REST compatible. You should clearly read a few books on the subject. Friendly advice, not a snarky comment.
I've read Fielding's thesis, thanks. I understand REST perfectly well.
> REST already has idempotent mutating operations, like PUT and DELETE. It's not just GET that's idempotent.
So what? PUT and DELETE don't have the necessary semantics. GET representation, apply operation listed in representation via POST. What more do you need?
> Honestly sorry if I sound snarky, but after 10 years on working with such APIs, and after reading countless books on the subject, it never ceases to amaze me how people still think that GET and POST are enough
You still haven't pointed out a single reason why GET+POST are not enough or how they "break REST". I'm not asking for "a ton of bibliography", I'm asking for a single example. An existence proof that my claim is false. It should be trivial if this shit ton of bibliography exists.
Frankly, most of this vaunted "bibliography" since Fielding's thesis has been non-REST crap. It's amazing how easily people can misunderstand a 150 page thesis.
But is that really a huge problem?
Look at more rigorous rpc standards with more rigorous standards and formal interface definitions: RMI, xmlrpc, CORBA, SOAP, Thrift, AMF... I'm sure there are loads and loads of real world systems using these and they have their place, but REST has succeeded in a large niche that they have not.
It's useful to remember that REST was borne and adopted mostly in reaction to SOAP and XMLRPC (which in turn were basically replacing CORBA and RMI to work around the firewall). XMLRPC was too loose, and SOAP was too formal (way too formal). REST hit the sweet spot.
However, it's sad that the result was often that people just retooled their crappy SOAP / RPC systems to use decent URLs and called it REST. My litmus test is usually "returning 200 OK on all calls" - if you're doing that, that's not REST. Use proper HTTP return codes and put additional error messages in the payload, it's not hard. Also, if you have a job queue, give each job a URL with the ID and GET that to retrieve status.
Nothing wrong with that, but don't call it a standard and don't try to name it something it isn't.
Most people don't understand REST. It is not a standard, it is not a set of practices. It is an architectural style and the web is built on it.
You can choose to follow the style (which is so much more than naming methods and URIs) or fight it. The dissertation is pretty clear about it[2], but most people ignore it because there are no code samples.
[1]: http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post (REST creator talking about the PUT misconception)
[2]: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm (Full REST dissertation)
And most people chose to ignore it -- and implement RESTful (mostly unrelated to REST as described by Roy) APIs, and no much harm has befallen them.
Ignoring REST is impossible, the web is built on it.
- The uniform interface is in every URI (if you use them, you use REST).
- The code-on-demand constraint is everywhere (if you use JavaScript, you're using REST).
- Hypermedia is everywhere (if you have links on your web page, you're using REST).
- The client-server constraint I don't even have to bother explaining (although WebRTC might bring P2P back in the game).
- The layering is everywhere (if you do haproxy, varnish, squid or similar, your using REST).
The _RESTful API_ thing is just a myth. People needed a name to discourage tunneling RPCs over HTTP, so they invented these loosely defined terms to push the idea. It should be called HTTPful, because it tells more about avoiding re-implementing HTTP features than it tells about the REST style.
And yet you don't provide a single concrete reason. And even go on to say the non-REST way you use REST at your team.
>REST is one of the more successful strategies we've come up with for connecting systems, this is just another case of letting perfect stand in the way of good enough. Using GET for non-destructive operations and POST for updates and deletes is a nice, portable compromise. I've been trying hard for years to find a reason to bother with PUT, but so far I've found it not worth the effort.
Note how none of this (or even few parts of what the author of TFA described) is actually REST as defined by Roy.
It's like reading a book on building a house and using ideas to build a shed. Sure your shed has electricity and a sink but it's still a shed, not a house.
Same with terms like RESTful. You don't call your shed a "house like building" as it's missing key pieces of a house.
REST requires HATEOAS. The only real implementation is the world wide web. Everything else is really JSON-RPC or some other protocol with a few ideas borrowed from REST.
There's usually a dollop of RPC in most APIs - and there's nothing wrong with that - but the 'pure vision' of REST is similar to the 'pure vision' of the Semantic Web. It's a dream for the next life not something we will receive in this one.
> I have full confidence that the authors considered these ideas, not laws.
"The authors" considered hyperlinking to be the one core concept of REST, all the rest is just fluff/transport concerns: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... (that's the bloke who wrote the original REST paper).
That's like saying the authors of the word "bicycle" considered it being two wheeled idea, not law, and you'll call your 8-wheeled ATV a bicycle because it has wheels and you think wheels are nice and solve your problem and the religion department is down the corridor.
Yeah wheels are nice and solve your problem, your motorised monstrosity is not a bicycle though.
To my mind the benefit of REST purism was that it killed SOAP. A similar thing has happened at other stages of tech development (e.g. CSS purism cured us of all those awful <table> excesses).
The purism was a mistake and the details were wrong but it was necessary to get everyone behind a common goal - getting rid of something worse.
This can also be solved by futures. Any POST that you'd like to retry, which will be any of them given the unpredictability of network partitions, can be bound to a future so the operation is applied only once and all future attempts simply return the bound value.
And it's not always safe to retry POSTs. If POST is an insert, for example, retrying it would produce two inserts. And this can have interesting consequences when processing responses. Suppose that you have sent a POST request, but before you could read the response, connection dropped. You didn't get a chance to read the status code, so you don't know if your insert succeeded or not. If it didn't, you want to retry - but you'll need to do a GET first to check the current state of affairs. OTOH, if you're doing a PUT, you can just retry immediately without re-checking.
My previous post already covered idempotent POSTs via futures. The fact is, only the application can decide whether a POST is safe to retry arbitrarily or must be made safe by binding to a future. The PUT is merely a small optimization that is now obviated by the spread of HTTPS.
Idempotence can be useful knowledge for client-side caches, so HTTPS doesn't obviate the value of the PUT (or, for the same reason, DELETE) vs. POST distinction.