Build APIs You Won't Hate: Everyone and their dog wants an API, so you should probably learn how to build them (2014)

11. Documentation

11.1 Introduction

Regardless of whether you decide to keep an API private or release it to the general public, documentation is incredibly important.

In the very early stages of development some API developers will rely soley on a Postman collection (discussed in Chapter 8: Debugging) to be a sufficient source of documentation for their API. This may be the case but as soon as the API is in use by more people than just the one developer with their one collection this quickly becomes a nightmare.

Even if the API is in use internally, without a single source of regularly updated documentation for your API you will be answering questions from anyone using the API about how that works non-stop.

If the API is public then… well without documentation nobody will use your API at all, which could drastically effect the successes of your company. Integration with services via an API these days is a very important factor for many companies, from startups to huge corporations, so do not go through the trouble of building something amazing only to have it completely ignored due to a lack of documentation.

11.2 Types of Documentation

There should be a few different types of documentation:

API Reference

The “API Reference” is sometimes refered to as “Endpoint Reference” and is essentially a list of all endpoints and their associated HTTP Methods, descriptions of what they do and a list of all arguments that can be passed with descriptions about what values work and in what format those values could be. That is a lot of work. But, it can be made easier with some tools. More on that later.

Sample Code

“Sample Code” is generally just a case of building one or two libraries or code packages in different languages and documenting their API with tools like phpDocumentor and showing lots of common scenarios, like “Search venues by name” and “Create a checkin with a photograph” to show the basics of how that code works. These examples reduce the mental barrier for a developer because they can see concrete examples in a language familiar to them, instead of being forced to think in terms of HTTP requests.

Despite your own personal preferences, please for the love of every good in the world make your sample code look as good as you can in each language. Words cannot express how frustrating it is when some Ruby developer smashes out some awful PHP code - because they are bad with PHP - and passes that off as a finished product.

Regardless of the language, most sample code should look very similar. This has the benefit of letting users switch between languages without having to start from scratch learning a new code package. PHP, Ruby and Python all have some concept of namespaces, they all have blocks or callbacks, they all have objects and hashes, they all support variadics and one day PHP will support named parameters. One day.

Guides or Tutorials

This is the easiest of the lot. Take a subject like “Authentication” and talk through it like a blog post. Images, diagrams, code examples of the libraries handling various situations in one or multiple languages using tabs, etc. Some people show examples using command line curl, but that can get pretty nasty as curl is not exactly known for being an interface full of sugar.

A great example of a set of tutorials is the SoundCloud API. Their “Using the API” page is a central resource which links to the API Reference for those who want to get their hands dirty, but also contains simple scenarios like “Uploading Audio Files” in multiple languages.

SoundCloud API Documentation - “Using the API”

If you check the examples out here Ruby, Python and PHP all look near identical (although I am not sure what happened to JavaScript).

Writing these guides takes a bit of time but that time will be given back in buckets, saving you answering the same questions over and over again. The other time saver is for when future you forgets how things work in 3 months, or you come back from a holiday rather frazzled and need a tutorial to step you through how things work. The amount of times I Google search a problem and find a blog I have written a few months ago answering it… It happens.

There are plenty of great tools around for static text-based documentation like this. Generally any Markdown -> HTML static site generator works well; Sculpin (PHP), Jekyll (Ruby) and Hyde (Python) all do this as well as each other.

11.3 Picking a Tool

There are no doubt multiple tools out there for generating your API/Endpoint documentation. Some recommend a system called Swagger which is a great looking tool and works with a huge array of languages. Sadly to me it seems to be somewhat of a black art.

Swagger defines a specification and various language or framework specific implementations come up with their own solution. For PHP the way you go about this is through a rather confusing (and poorly documented) set of annotations with strange names. Furthermore it requires you to put these annotations throughout a large chunk of your application, including data mapper style models, which you might not even have. It wanted property-level annotations, and neither my models or Fractal transformers have properties, so this was a wild and whacky way to try and work.

Another tool called API Blueprint takes care of this nicely. A company called Apiary released this tool as open-source, and as their entire company is about API generation it seems like rather a good fit.

11.4 Setting up API Blueprint and Aglio

API Blueprint has a very easy to understand set of Getting Started instructions which has a series of approaches to creating your documentation with various languages and tool combinations. They are working on a Ruby utility and .NET seems to be covered. Sublime Text has [a plugin][st-plugin], but by far the easiest is the command-line executable called Aglio.

There is one caveat: this tool uses NodeJS. That sounds like a blocker to some but it should not be. Only the command-line utility requires NodeJS, much like some command-line tools require Ruby or Python. Install NodeJS and move along to the next bit.

Step 1: Install NodeJS

If you are using OSX then Homebrew makes this very easy:

1 $ brew install node

Otherwise the NodeJS website has instructions for your operating system.

Step 2: Install Aglio

Install this utility as a command-line executable:

1 $ npm install -g aglio

The -g switch installs the utility globally, instead of just into the current folder.

Step 3: Generate Example Docs with Aglio

The sample code for the book includes the Aglio example markdown file, which will help illustrate how easy it is to generate documentation HTML:

1 $ cd ~/apisyouwonthate/chapter11/aglio-example

2 $ aglio -i example.md -o index.html

Step 4: Generate HTML and Open in Browser

Create some sort of web server (XAMPP, WAMP, MAMP, Pow, shove it on FTP or whatever) and view the contents. This book has used PHP as an example before, so let us continue that trend:

1 $ php -S localhost:8001

Now browse to that address in your favorite browser and you should see some very attractive sample output.

Example output of Aglio generated HTML

Looks amazing right?

Step 5: Find a Plugin

Writing Markdown then switching over to the terminal and running a command can be a tricky workflow, so try and find a plugin for an editor you like which can help. If you use Atom then there is an Atom plugin you can use, but there are doubtless other options available.

11.5 Learning API Blueprint Syntax

To make the output reflect your API documentation, the Markdown source files will need updated. While they are generally just Markdown, there is a specific format to this, known as “API Blueprint format 1A”.

Go to the following location and open up example.md:

1 $ cd ~/apisyouwonthate/chapter11/place-example

The rest of this section will walk through this example.md and explain what various parts mean.

Meta Data

This is simple. The API title, URL, introduction, etc is just some Markdown:

Very start of an API Blueprint markdown file, showing meta data