A discussion on API Documentation and Hypermedia | Glenn Block


A few weeks ago, I read a great post from Kin Lane where he was talking about the Open API movement in government. One of the things he discussed was the momentum around APIs and adoption of emerging standards for API documentation. In particular he mentioned Swagger (which I was familiar with), Blueprint, and RAML.

Seeing this traction and being a general fan of helping move the API adoption ball forward, I thought it might be interesting to explore using one of these formats for Splunk’s API. So I decided to wade in to each of the formats and well share my initial thoughts on the best of all places, twitter! Flash forward a bunch of tweets and that turned into a very engaging twitter discussion (or more like a tweetacaine) between Kin, myself and the authors of the different standards, namely Tony Tam (@fehguy) of Swagger, Uri Sarid (@usarid) of RAML, and lastly Jakub Nesteril (@jakubnesetril) of API Blueprint as well others who weighed in like Rob Bihun (@robbihun). This then led to a bunch of us heading to Jabbr where we could stop spamming the rest of the twitterverse and carry on a real conversation.

It was a really interesting discussion where we discussed the goals of each format. Being the hypermedia guy that I am, I was very interested in the level of (or lack of) support for hypermedia in these formats.

After all the discussion it turns out there is a lot of commonality between the different formats:

  • One key thing that came out of the conversation was that all of these standards seem pretty intent on not repeating the mistakes of WSDL. That is the documentation is a guide, and describes a contract, but the description is just to help you, but not a language you must speak to get in the door. And this my friends, is a very GOOD thing!
  • The main difference seems to revolve around the types of capabilities the formats offer, which does impact the conceptual overhead for working with that format. Swagger stands out as trying to be as minimalist as possible, but there is a tradeoff there in how far you can go with it.
  • Another key difference appeared to be around URIs. Swagger appears very much to be centered around the notion of URIs as APIS, while the others seem to take a more resource oriented approach.
  • Blueprint and RAML want to offer more value beyond just docs. Blueprint for example supports Dredd for testing your server API. Blueprint wants to even help you implement your server using the Blueprint doc as a guide for even helping you generate a server implementation.
  • None of the formats (at that time) had any real first class support for hypermedia.

Kin being the awesome guy he is, captured the entire web 2.0ish (if there’s such a thing) discussion from twitter to Jabbr in a recent blog post here. It’s an interesting experiment as it is basically just a capturing of a really large brain dump. It’s like being in the room with us though, everything is there :-)

One thing positive that came out of this discussion is it helped reignite some momentum around first class hypermedia support in API Blueprint and RAML. For Blueprint, there’s an active discussion going on now on a new Resource Blueprint on github here.

Another piece of progress, Kin has had some great further discussions with the creators on the motivations behind their libraries which he’s written up here.

I am really thankful to Kin, Tony, Uri, Jakub and Rob for the great convo!

What are are your experiences around API documentation? Have you used any of these formats? Are you using others?

Regardless, it’s a great time for APIs!