Featured in
Architecture & Design

Mini-talks: The Machine Intelligence Landscape: A Venture Capital Perspective by David Beyer. The future of global, trustless transactions on the largest graph: blockchain by Olaf Carlson-Wee. Algorithms for Anti-Money Laundering by Richard Minerich.

Featured in
Operations & Infrastructure

Mini-talks: The Machine Intelligence Landscape: A Venture Capital Perspective by David Beyer. The future of global, trustless transactions on the largest graph: blockchain by Olaf Carlson-Wee. Algorithms for Anti-Money Laundering by Richard Minerich.

Featured in
Enterprise Architecture

Mini-talks: The Machine Intelligence Landscape: A Venture Capital Perspective by David Beyer. The future of global, trustless transactions on the largest graph: blockchain by Olaf Carlson-Wee. Algorithms for Anti-Money Laundering by Richard Minerich.

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

REST APIs are a case of good intentions run amok. The point of REST was to *eliminate* specific APIs. Not cause their proliferation.

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.

That said, RESTians saying you shouldn't have an API are somewhat vacuous because they offer no good alternative. Custom media types ain't.

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.

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:

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.

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."

"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."

"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."

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?

I have a little trouble understanding the apparent frustration of some of the REST critics. I guess we must have reached the Trough of Disillusionment.

As for myself, I thank God every day that I am not at the mercy of a clueless CIO who bought the SOA and WS-* hype from the vendors.

A few years ago I thought myself that WS-* was the next big thing to bet on.

It didn't take me long to notice that especially the people who seemed to know what they were talking about - such as Tim Bray (co-wrote the XML standard), Steve Vinoski (distributed computing guru, worked on CORBA standards, among other things) and Stefan Tilkov (reformed CORBA and WS-* expert) - tended to take a dim view of the WS-* standards and vendor-driven SOA.

These guys had courage to champion REST back then. It is easier now, with examples such as Google, Yahoo, Amazon and Facebook. (Coming to think of it, the parallels to the adoption of Agile software development are striking.)

At the end of the day, true REST is only good at CRUD and basic querying. Once you need to do something beyond that, which is very common in an enterprise environment, REST starts to present more problems than it solves.

SOAP-based RPC isn't perfect by any stretch of the imagination, but at least it accepts that there are things HTTP verbs aren't suited for.

For example, the Amazon API covered in Richardson and Ruby's book had some shortcomings (I think it was insufficient use of hyperlinks), but it was good enough to serve as an example for some major points.

The new Facebook API is better and - perhaps not by coincidence - more "RESTful" than the old one.

When it comes to our own APIs, we are of course free to do a perfect job. :-)

There is so much confusion about REST that it's almost impossible to have a meaningful discussion about it. Someone says REST and I generally have no idea whether they mean REST in the abstract (Fielding) sense, REST in the RESTful Web Services sense, or if they just really mean XML/JSON over HTTP.

The reality is that RESTful web services cover most of the concerns addressed by WS-* or eliminate the need for them. There are a few exceptions but it's pretty close to feature complete. It takes a while to get it. I thought I did and found out I misunderstood some key points after my first attempt.

I also take issue with the idea that there will be one spec that everyone will use. People only argue this when the spec they support is perceived to be the obvious front-runner and it's being challenged. It's also an anti-innovation/anti-competition standpoint.

Also, software vendors tend to over-inflate their importance in terms of the impact their technical decisions really have on customers. As a consumer (and producer) of services I don't care all that much whether you use SOAP or REST or whatever. Focus on making usable services/APIs available and stop telling everyone else what to do. I've already accepted my vendors won't all be using the same approach. It doesn't really matter what you use as long as it isn't completely crazy.