A discussion on API Documentation and Hypermedia

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!

This entry was posted in REST and tagged . Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • http://www.diligentsoftware.com Peter Stephens

    +1 on reading RESTful Web APIs.

  • http://blogs.msdn.com/gblock Glenn Block


    Done wrongly yes, but I think we can achieve a balance. ie an SDK that uses the affordances under the hood, but gives the user something easier to digest.

  • http://blogs.msdn.com/gblock Glenn Block

    Thanks @inadarei:disqus

    I agree having an SDK is very valuable and makes the API more approachable. You make a good point on needing guidance / help to write a hypermedia based SDK. Essentially you need to write a client that though it may have hard-coded members, under the hood they look for the presence / absence of links with specific rels and follow them or you have methods which use forms under the hood. I agree this is an area that we need a lot more help to make it easier to adopt a hypermedia approach.

  • http://blogs.msdn.com/gblock Glenn Block

    Thanks Matthew.

    Hypermedia is still making it’s way into the mainstream. Part of the problem is not enough good examples. Folks think it is very esoteric and don’t understand how to apply it real word.

  • http://blogs.msdn.com/gblock Glenn Block

    Hence where profile helps

  • http://blogs.msdn.com/gblock Glenn Block

    Rick Strahl WSDL provided that ability, but the tradeoff was a ton of pain as changes on the server generally break clients, which was a general nightmare, in particular in larger companies. I have heard this continually and witnessed it! The main reason is because the definition heavily ties to the actual implementation. Even though you are not coupled to internal details you are coupled to a contract that still relates to the implementation.

    In the REST/HTTP world there is an answer that still allows you to have a definition, but that definition is the media type, OR a profile (https://tools.ietf.org/html/rfc6906) if you are using an existing media type. A difference though is the definition is not at all tied to implementation and if designed correctly is version tolerant / allows change.

    The question of whether or not to layer tooling on top is something that is starting to be looked at more heavily. With efforts like ALPS (http://alps.io/spec/) and the other efforts discussed here, I think this will become plausible.

    However, I know of many stories of companies that using the centralized documentation of the media type alone, has been sufficient. Large ones like Yahoo which uses tons and tons of APIs internally.

  • http://www.bizcoder.com Darrel Miller

    One of the constraints of REST is that messages should be self-descriptive. There should be some form of identifiers in the message that point you to documentation that describes exactly the format and semantics of the message. The fact that people use HTTP to return ‘application/json’ documents and rely on out of band documentation to correlate the response schema with the URI is a major problem. It’s not a REST problem though. It’s a problem with a flawed architectural style that people mistakenly call REST.

  • http://www.freshblurbs.com/ inadarei

    Welp, there’s the fact that APIs that call themselves RESTful (including the big, famous ones) are just avoiding WS-* stack’s complexity and winging it, but really have nothing to do with Fielding’s definition of RESTfulness.

    But that aside, if you haven’t read it yet, I think you might enjoy this book a lot: http://shop.oreilly.com/product/0636920028468.do

  • Rick Strahl

    I was just thinking around this today as I’m working with a REST service where the service documentation has gone out of sync with the implementation. I’m down to pinging the developers to get the ‘real’ deal which is extremely time consuming.

    Say what you will about WSDL, one of the nice things was the ability to very easily connect services together and get (usually) a current schema to work against. With REST today this is a lot more painful. The best one can hope for is that the service’s provider has an SDK that provides the bindings for you in your platform of choice, or else you’re spending a painful amount of time creating an object model around the service in your application.

    I haven’t been following the schema discussions, but the more I’ve been working with REST the more I heartily wish for something standardized that would help bridge this gap and bring at least basic Schema services and auto-discovery of resources. Many an argument I have with more enterprise oriented folks revolves around the schemaless-ness of REST (as well as the ability of WCF’s services to use different protocols) and there’s no good answer for that today with REST as provided in the mainstream.

  • inadarei

    Good point. I should have been more specific:

    SDKs are supposed to be media-type-specific, not API-provider specific. Given wide adoption of a handful of standard media types, decoupling benefit will be kept in-tact.

  • http://www.bizcoder.com Darrel Miller

    Be careful what you wish for when it comes to SDKs. I agree that tooling to support hypermedia APIs is very useful. However, what we need is general purpose hypermedia tooling, not wrappers around specific APIs. It is very easy to lose the decoupling that hypermedia brings with client side libraries.

  • Matthew Whetton

    Great article – I find it pretty surprising that hypermedia seems to get so little attention, especially given the traction that REST based services have got over the last few years

  • inadarei

    Great post, Glenn. Very excited to see discussions happening around non-URI-centric/Hypermedia documentation tooling. Properly documenting the API when building http://pmp.io was one of my biggest challenges. I came out of that experience with some scars/take-aways. Here they are, for what its worth:

    1. Most important documentation for a Hypermedia API is that of the media type used. This probably mostly just requires good technical writing and a suiting Markdown editor, if that’s your kinda thing.

    2. Hypermedia APIs need good client SDKs. They really do. As such, the next important pieces of documentation are:

    2.1. A How-to for writing an SDK, if you are implementing one in a new language

    2.2. A reference SDK that people can peek into and poke.

    2.3. SDK user guide / super-simple Getting Started guide. Speed of zero-to-useful-data is critical.

    These needs are very different from documenting URIs or even resources being exchanged. Other people’s experience may, of course, vary, but if this is even roughly the accurate list—I still have no idea what tooling would make producing them easier.

    I sure would like to know, though :)