Understanding the Good in “The Good, the Bad and the Ugly of REST APIs”

With several dozens of APIs getting published every month or so, it is kind of become a routine for a seemingly innocent “How to do REST” or “Guidelines for REST APIs” kind of blog posts become source of controversies around applying REST principles properly.

Last week, it was the turn of George Reese’s blog post titled “The Good, the bad, and the ugly of REST APIs” for the controversy.  There were several reactions and reactions to reactions on all aspects of his post.  Following tweet from George indicates the mood:

One of the things George’s blog advocates under “Good” list is:

Supporting both JSON and XML

I know you love {JSON,XML} and you think everyone should be using {JSON,XML} and that the people who use {XML,JSON} are simply stupid. But you’re not building an API for yourself, you are building it for everyone, including those who think {XML,JSON} rocks and {JSON,XML} sucks. I don’t want to get in the technical merits of either language or even the possibility that there might be distinct use cases for JSON vs. XML. The bottom line is that there are people out there who want to consume APIs in both languages and it’s just not hard or complex to support both.

To which William Vampenepe reacts in his blog post:

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

Now that confuses me. Supporting JSON and XML in my mind is no different from a resource supporting multiple media types and serve an appropriate media type using content negotiation.  The post he links to talks about SOAP and REST as multiple protocols. I don’t see the connection.

The other item on George’s “Good” list is:

Providing solid API documentation reduces my need for your help

Solid API documentation enables an individual to both understand the simple examples that help them get started as well as the complex ways in which they can leverage the API to accomplish advanced tasks

That doesn’t seem like a statement to be argued with, isn’t it ?  Apparently not so. Jan Algermissen posted a comment saying:

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”

This comment was met with ridicule by many folks including George and William terming it as nothing but silly.

My takeaway from that comment was that the documentation should focus on media types as the rest of the behvaiour of dealing with media types is fairly standard with REST.

Clearly, Jan Algermissen is no newbie to REST. But I am still baffled by the first part of his statement.  How can a little documentation with examples of request and response payloads (even at the risk of duplicating something very obvious in REST way of doing) make it so against REST.

Stu responds with his blog post defending Jan Algermissen’s comment and many other things.

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.

I am still trying to digest parts of Stu’s post. Most developers learn the best practices by looking at what experts in that domain recommend or see mimic real-world APIs from popular web sites (twitter.com, facebook.com etc). Unfortunately, of late, these are the wrong sources to learn the best practices from (Remember the hashbang controversy).

Here is something even more basic. Try and get a bookmark-able link to a specific tweet on twitter.com site.


(Updated 14th June 2011)

I would like to add one more the list of  “good”  of REST APIs.  I am sure all REST purists would now cringe at this. Try and publish WADL for your API. Goal is not to be able to do all weird stuff that tools force you to do with WSDL while consuming the service.  But it definitely helps your API consumers to leverage some tools that would further help them to understand the API better.  For example, check out this cool API console tool from apigee. Apigee API console takes a WADL and provides a nice way to navigate the API, exercise the API (including OAuth), look at the request/responses  and learn iteratively – all with zero coding and based completely on WADL.

It already supports several public REST APIs as an example.


2 thoughts on “Understanding the Good in “The Good, the Bad and the Ugly of REST APIs”

  1. A couple of responses.

    1) WRT to media types, do you think that the more media types the better? It seems to me, you offer additional ones to the extent that they offer a different value or address a different use case. If they’re not different enough to address different use cases (as I think is the case between JSON and a simple XML equivalent) then you’re adding more trouble than you’re removing. OK, I won’t repeat the whole blog post I wrote about this, linked above (Two versions of a protocol is one too many).

    2) Now that’s a cheap shot, but if it’s true that “If you document an API, you API immediately ceases to have anything to do with REST” then what happens if you write a beautiful RESTful interface (no documentation!) and I come along and document your API? Does it stop being RESTful? Now that’s a new definition of vandalism: someone who document somebody else’s API to destroy their RESTfulness. 😉

    3) WRT to bookmarkable link to a Tweet, I am not sure what the problem is. Here is a link to my last tweet:
    What’s the issue with this URL?


    • William,

      Thanks for the response.

      1) As I understood, media types are a representation of the underlying resource’s model. Now, with all sorts of different consumers out there, it would make sense to have media types that suit the consumption model of the consumer. Web architecture principles and HTTP content negotiation has been advocating this for ever right. I see and understand your argument against supporting multiple protocols (esp REST & SOAP examples), but I am still not convinced that it applies as much to multiple media types for the same resource in a REST only API.

      2) Well said :-). I was a bit taken a back to see such extreme view points on the documentation issue. Think about what happens if someone suggests publishing WADL for REST APIs as a best practice 🙂

      3) I have been using twitter for some time, but getting a perma-link to a specific tweet was never obvious. After your reply, I went back to twitter.com and hovered on all the links and finally found that the text that indicates the time for the tweet “10 minutes ago” etc actually points to the tweet’s perma-link.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s