Oana Cocarascu

hey doc

We’ve previously mentioned our principles in designing APIs. However, having a REST API also requires some documentation. Good documentation shouldn’t be just a listing of endpoints with parameters. Ideally, it should give enough detail and provide examples — tell me everything I need to know and that I’ll ever want to know.

decisions decisions

There are quite a few tools out there that try to make the API documentation an easier task: jsondoc, wsdoc, swagger.

Some people automate the generation of documentation while others just write it by hand mainly because documentation automation does not guarantee good documentation.


For the project that I’m currently working on, we decided to use apiary (causing quite a buzz..). It’s more of a design tool, encouraging collaboration among multiple users.

Before you start, you might want to check the format for describing the API Blueprint. It comes with a Markdown syntax, but it provides code samples in order to get the documentation up and running.


The above example shows a basic generated documentation while providing a glimpse of the syntax.

Apiary allows for server mocking, representing a quick way to experiment with the API. It also provides a traffic inspector so that you can send API calls through Apiary’s debugging proxy.

what now

This is what our very simple example would look like.

apiary trailers

It does mean that you have to maintain the documentation, update as you write the code — changing a single URL in the code means that you’ll also have to change it in the documentation.

what do you think?

What is your approach when it comes to API documentation? We’d like to hear your opinions so do leave us a comment below or send us a tweet.

blog comments powered by Disqus