New Early adopter or innovator? InfoQ has been working on some new features for you. Learn more

Yet More Trouble with REST APIs?

| by Mark Little on Jun 12, 2011. Estimated reading time: 5 minutes |

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:

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?

Rate this Article

Adoption Stage

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Trough of Disillusionment by Jens Meydam

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

I went with REST, and I never looked back.

Re: Trough of Disillusionment by Faisal Waris


Just a minor correction, nobody is actually doing REST (as outlined by Fielding) because it is really very hard to apply REST in practice.

What you have are Web APIs - not REST - which is what is frustrating the experts.

So most everyone claiming to do REST - is not; and worse, they don't even know that.



Re: Trough of Disillusionment by Robert Dean

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.

Re: Trough of Disillusionment by Jens Meydam

Let's not the best be the enemy of the good!

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. :-)

Confusion by James Watson

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.

Re: Trough of Disillusionment by Jens Meydam

No, sorry, that is just wrong.

Grab a book on REST (there are a couple now, a more recent one by a guy who used to be an architect at Yahoo and is now an architect at Ebay) and read it from cover to cover. You may be surprised.

There are quite a few good presentations and articles on InfoQ as well.

Just to lighten up the debate by Jens Meydam

Just to lighten up the debate - does anyone remember this timeless piece?

Re: Just to lighten up the debate by justin simonelis

haha that's hillarious. all these "standards" are a joke, who has time to keep up?

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

8 Discuss

Login to InfoQ to interact with what matters most to you.

Recover your password...


Follow your favorite topics and editors

Quick overview of most important highlights in the industry and on the site.


More signal, less noise

Build your own feed by choosing topics you want to read about and editors you want to hear from.


Stay up-to-date

Set up your notifications and dont miss out on content that matters to you