API Series: Help and Documentation

There are a lot of traits that make an API great. Easily consumable, predictable, discoverable, wide open, and a consistent URL design are the first that come to mind. But an often overlooked and undervalued area is documentation. Without proper documentation, developers are left to fend for themselves trying to figure out how to use an API, which is both time-consuming and error-prone. We’ve all been there, frustrated by an API and its lack of documentation.

Of course, there are some shining examples of API documentation done right – the Stripe API and the Github API immediately come to mind. Both are formatted and laid out well, easy to read, and contain all necessary information required to use their respective APIs.

For the Znode API, we knew from the beginning that documentation would play a major factor, and in fact, we quite often used other API docs as inspiration (in particular the Stripe API). We wanted users of the Znode API to feel at home and comfortable, and one of the best ways to do that is by providing clear, understandable documentation.

In fact, we went so far as to make the Znode API documentation simply *part* of the API itself (you can see a version of it at api.znode.com). There is no Word document or PDF file that you have to read through to know how to use the API. The API is a living, breathing artifact that you can understand as you use the various endpoints. The homepage of the API lays out all of the parts that make up the API and what they mean, while each endpoint help page lists all of its supported features and sample data to get you up to speed quickly (which also serve as the perfect reference material).

The Znode API documentation is as vital to the API as the API itself, because in our eyes, they are one and the same.