Tuesday, October 29, 2013

An Introduction to Apiary

While exploring what tools are available for documenting APIs, I came across a plucky startup from the Czech Republic called Apiary. Apiary is an API authoring and collaboration tool, that encourages UI first like design - except for APIs of course. In fact, document orientated design might be a more accurate moniker. You can write your Api in a structured syntax, and then publish that API into beautiful HTML documentation. You can collaborate with your colleagues, and customers alike, inviting them to give you feedback before you ever write a line of code.

Apiary aims to be the Github of the Api documentation space. It is a typically lofty goal from a startup, but from what I've seen so far, they have every chance of achieving it. Just as Github built on top of open-source tools, so too does Apiary with their own open-source initiative: API Blueprint. API Blueprint is an open source standard and toolkit for defining and parsing API documentation.

Blueprint Syntax

There are currently two syntax standards in play: the old and the new. When I created my first API last week, the starter sample text was in the old format, but checking again today, that appears to have changed.

The Old Syntax

The old syntax is (obviously) on the way out, but I want to mention it here to save you any confusion if you do come across it. Markdown syntax is allowed to add formatting in comment/description areas. An complete document would not be a valid markup document. Actions were defined with the help of the < and > characters, which elegantly illustrated the direction of the communication. Here is a example of how to define such an endpoint/action:

The New Syntax

In the new syntax, the entire document complies with markdown syntax. Reserved words are used to extract additional meaning from various parts of the document (headers, list items, etc.). One of the nice things about the change to all validating markdown documents, is that Markdown aware services such as Github will now render them in an aesthetically pleasing manner. The new syntax looks like this:

Like XML (or indeed Erlang), documents written in the version 2 syntax must have their first line be
FORMAT: X-1A. This will ensure the correct parser, and validator are used. If you forget this line, you might find your document being the subject of incomprehensible validation errors.

Currently, the best resource for example snippets of the API syntax is in a Github repository (of course). It is worth pointing out that, as Github will format these sample documents according to the markdown standard, to get any kind of value from them, you need to view them in raw format. While the examples are useful, to really get to grips with writing the the API documentation you will need to read the language specification. There is also a nice third-party example in the form of unofficial documentation of the Tesla Model S api. You can also checkout the apiary tutorial.

Blueprint Tools

There are a number of Api Blueprint tools that are essentially the reference implementations of the standards. The tools and the standards are open source so others can (and most likely will) create additions and variations to the tools currently available.

Snow Crash

Snow Crash parses Api Blueprint documents to produce a more machine friendly representation of their content (JSON). You can then take this representation to do all kinds of automation magic depending on your needs. Check out the Snow Crash Github repository for more info. 


Dredd is a great example of what you can do with the machine friendly representation of your API. Dredd will take your API documentation and use it to create a series of tests which it will then run against an end point of your choosing.

Check out the Dredd Github repository for more info.


  • I've been playing with Apiary and API Blueprint for about a week now, and I'm already hooked.
  • A standard syntax and document structure helps to design better APIs. 
  • The collaboration aspect means there is no excuse for not getting feedback early. 
  • The lack of vendor lock-in is a real comfort. Just like with Github, I know that if ever I am unhappy with the service, I can always move my documentation in house, or to an alternative service.
  • Apiary also supports multi-markdown which covers some of the feature gaps in plain Markdown (such as tables).
  • I'm looking forward to taking Dredd for a spin, but I'm not in a rush to dive into the code just yet.