Yet More Trouble with REST APIs?

Recently George Reese was writing about his shared experiences with Adrian Cole on using various SOAP and REST APIs for the Cloud and which we reported earlier. Now George's original entry has sparked a lot of debate on twitter and various blogs. For instance, William Vambenepe agrees with many of the things he has to say, but disagrees with a few, such as supporting JSON and XML:

I disagree: Two versions of a protocol is one too many (the post behind this link doesn’t specifically discuss the JSON/XML dichotomy but its logic applies to that situation, as Tim Bray pointed out in a comment).

And William also doesn't agree with George on his statement that REST is better than SOAP:

Not necessarily true for all integration projects, but in the context of Cloud APIs, I agree. As long as it’s “pragmatic REST”, not the kind that involves silly contortions to please the REST police.

Interestingly one item that William picks up on ...

Providing solid API documentation reduces my need for your help: Goes without saying (for a good laugh, check out the commenter on George’s blog entry who wrote that “if you document an API, you API immediately ceases to have anything to do with REST” which I want to believe was meant as a joke but appears written in earnest).

... is from Jan Algermissen and who, to answer William's comment, says in all seriousness:

Regarding "Providing solid API documentation reduces my need for your help". If you document an API, you API immediately ceases to have anything to do with REST. The contract in RESTful systems is the media types, *not* the API documentation. I suggest you move that section to "The Bad"! See:http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

However, Stu Charlton sparked probably the most discussion and summarised in 5 points in his own article on the trouble with APIs.

1. REST APIs are a case of good intentions run amok. The point of REST was to *eliminate* specific APIs. Not cause their proliferation.
2. When someone says you shouldn't document a REST API, they're saying you shouldn't have an API. Not that you shouldn't document.
3. That said, RESTians saying you shouldn't have an API are somewhat vacuous because they offer no good alternative. Custom media types ain't.
4. Thus, IMO, until we have a workable generic media type or two for the 80% case of "REST APIs", we're just growing a frustrating mess.
5. I've sort of half given up on REST advocacy because it's pretty impossible these days. People want to ship APIs that will be valid for the next next 6 months, not build systems that will evolve over a decade or more.

And talking specifically about Jan's earlier comment, Stu has this to say in support:

Jan Algermissen's comment about how when you've documented an API, you're not really doing REST, is actually spot on, fundamentally, but is met with ridicule. I can completely understand how vacuous the comment sounds if you just want to ship an API nownownow, are being short-term practically minded, or are just playing buzzword bingo with architectural styles. But if we actually want to leverage the benefits of the style, we'd work on the core issue of having a generic media type or two for these sorts of use cases.

As appears to be the case most often with REST, Stu's article also sparked a lot of interesting comments from people on both sides of the argument. Furthermore, it can be argued that this debate is related to our previous article on whether or not REST can be considered successful in the enterprise, and similarly possibly why Jean-Jacques believes we now live in a POST REST/SOAP World.

The problem that REST has created [...] is that now any API designer gets a free license to be a distributed computing guru, artistically deciding where to put things like version and credentials, and encode actions and queries as they please amongst a wealth of headers, tokens, query parameters, bodies and what not. If you ask me, REST has produced the software industry WOrst Atrocity ever.

Stu concludes with some rule changes that he believes are direct consequences of using REST:

1. You cannot assume that the end user of your service is going to be a programmer (or a browser). Stu contends that if your goal is for a programmer to learn your API then there's no reason to use REST.
2. You cannot assume that only one site will be implementing your interface. "The whole point of the Web is sharing information - publishing an API bakes in the assumption that YOU, the publisher, are in control. It is the consumer, on the other hand - the agent itself, that's in control of how/what the information is consumed or manipulated."
3. "The semantics of the interface that need to be documented are the media type that you use to describe your data and links. The structure of your URIs really shouldn't be a part of said semantics."
4. "But doing this in a custom media type implies #2, that you're the only person implementing your interface. Of course, every media type has to start somewhere, but it really doesn't help matters unless you understand that others may be *implementing* your interface, not just *talking* to it."

His final rule change is worth calling out separately as it has been the subject of much debate over the years:

The best we can hope for is some person/organization to step up with a generic media type or two + guidelines that help describe and document a Web of Data interface for accessibility by programmers. Call it a description language, if you'd like. Some RESTians don't like the idea of a description language. I think it's an essential 80/20 piece if developers are going to actually *use* the architecture the way it was meant to be used.

So what do you think? Are we simply missing well defined rules for designing good REST APIs, or is this really a lost cause as JJ suggests?