December 5, 2013

Building Modern API Documentation

I’ve been busy building an API documentation template over the last month or so at TripIt. In the process, I’ve gathered a few tips that should help you build better docs for your website’s API.

It’s probably best to start off with a good example. As far as I can tell, the shiniest shining example in the documentation scene is Stripe’s docs.

Screenshot of Stripe's API documentation

Literally oozing with modern. Descriptions of each endpoint are on the left, and code examples are on the right. The entire documentation is on one long page. There are tabs in the top right to switch the programming language of the examples. Stripe is an great example of well-polished documentation.

However, getting Stripe-level docs is not as simple as just copying the basic layout.

Navigation Pitfalls

Single page docs are great. They are faster to search through, easy to print, and their linearity is nice and simple. However, their long length presents unique navigation problems. Let’s look at PayPal’s API docs.

Screenshot of PayPal's documentation

PayPal’s docs have roughly the same layout as Stripe; descriptions on the left, code on the right. It’s a pretty good format. However, if we look more closely, PayPal has no third column for the table of contents. As the page scrolls, the table of contents will drift out of sight. I call this the disappearing table of contents of doom.

Long pages need a fixed table of contents. Without one, they will be a pain to navigate. PayPal’s language-switching tabs also drift away, which means users have to scroll all the way to the top of the page to switch programming languages.

Navigation should be fixed to the page view.

Next, let’s talk about the URLs of long pages.

Don’t Use Normal URLs

This is another detail that Stripe gets right. Visit Stripe’s docs, scroll down the page, and take a look at the URL. It’ll only take you a second.

Did you see that? As you scrolled, it changed. When you scroll to Stripe’s Authentication section, some Javascript on the page quietly replaces the hash of the URL with #authentication.

At first glance, this is not the behavior the user would expect. Most pages on the web don’t change their URL as the user scrolls. Wouldn’t this non-standard behavior be confusing?

Well, what are users’ expectations about URLs? If you’re looking at normal, many-paged documentation, and you need to send your coworker a link to…say…the launch_kitten endpoint, you’ll probably navigate to the page that describes “launch kitten”, copy the URL, and send it to your coworker. All is fine and dandy, and everybody is happy. Except the kittens.

Cat in a Catapult

However, this is not true for extremely long pages. Scrolling down to a section and copying the URL will make a link to the top of the page, which is a long scroll away from the launch_kitten endpoint. The URL does not represent the content currently on the screen. So although changing the browser’s hash as the user scrolls might be non-standard, on very long single pages it actually upholds the normal concepts of URLs, rather than subverting them.

There’s one other thing to note about Stripe’s URLs — changing the programming language also changes the URL. This means links don’t only link to the right location, but the right language, too. If no language is specified in the URL, the last viewed language is the default. The URLs of Stripe’s docs represent an exact state and position within the page.

URLs should always point to the current position and state of the page.

Finally, let’s take a look at what Github’s doing.

Host Docs with Github

Github’s doesn’t put their API docs on a single page, but their documentation is unique in another way. They host their docs in a public Github repository. Just take a light scroll down the contributors list. Every time a developer finds a problem with Github’s documentation they can fix it.

User-editable documentation has more benefits than just getting developers to help out. It helps see where users are having trouble, and shows developers that documentation is updated and problems are addressed. It creates a sense of reliability. Everybody wins.

User-editable documentation is better.

Obviously, hosting documentation on Github has drawbacks. Stripe inserts live API keys into their examples, which is impossible with Github pages; they only host static files. Just don’t overlook Github as a possibility when you’re thinking about where you’ll host your API docs.

Lessons to Learn

To review, these are a few ways to build better API docs.

  • Navigation should be fixed to the page view.
  • URLs should always point to the current position and state of the page.
  • User-editable documentation is better.

If you’re looking for a single-page, Github-hosted, easy-to-use API docs template, consider Slate, a open source documentation template I’ve been working on at TripIt. You can write docs in Markdown!