If you’ve been spending much time on the Nordic APIs blog, you’ll know that developer experience is something we’re passionate about. Creating a smooth and enjoyable experience for those implementing your APIs is essential with just how much competition there is nowadays, and API documentation is one of the keys to success.

In a previous post, we talked about the features API documentation can’t live without, and more broadly the core ingredients for a developer center, but today we’re going to dive head-first into the nitty gritty of it all and look at five examples of excellent API documentation.

As a quick heads-up, these API reference docs are great for many more reasons than one. But this is a blog post — not a book — so we’ll give you a quick run-down of the example and then focus in on just one of their best-executed features. To keep you informed of the bigger picture, though, we’ll refer back to this five-part checklist of documentation basics throughout the post:

Authentication guide ☐
Quickstart guide ☐
Endpoint definitions ☐
Code snippets ☐
Example responses ☐

1. Stripe API Reference

We challenge you to find a discussion about the best API reference docs that doesn’t include Stripe. Spoiler alert: there isn’t one. The Stripe API documentation, or the Stripe API Reference, is a work of art. It features a sleek and cool two-panel design, with explanations written in plain English on the left and handy code snippets on the right. As you’d expect, it has all the crucial information you need to get going right away.

What We Love About It

It’s hard to point to a single, cool feature of the Stripe API documentation. In truth, there aren’t any shiny bells and whistles — and that’s probably what makes the Stripe API reference so good. It has all the information you need to get started, presented cleanly and sensibly. The lesson: don’t overdo it.

Does It Tick the Boxes?

Authentication guide ☑
Quickstart guide ☐
Endpoint definitions ☑
Code snippets ☑
Example responses ☑

2. Twilio Docs

Another oft-cited favorite of developers is the Twilio docs. The Twilio Docs use the same, two-panel style as the Stripe API Reference (which we’re a fan of). However, Twilio’s API documentation feels a little easier on the eyes, with a well-chosen font and bright, contrasting links. It shouldn’t need mentioning that there are plenty of code snippets which you can copy and paste over right away.

Does It Tick the Boxes?

Authentication guide ☑
Quickstart guide ☑
Endpoint definitions ☑
Code snippets ☑
Example responses ☑

What We Love About It

What we love about the Twilio Docs is just how much depth they provide — even for beginners. Just look over to the side navigation panel: they’ve included pages like “What’s a REST API, anyway?” and “How Twilio’s API uses webhooks.” Their answers to these questions give developers a quick, bottom-up insight into everything they need to know. The lesson: be beginner-friendly.

3. Dropbox API Documentation

The Dropbox API documentation is yet another fantastic example of excellent reference documentation. Instead of using the same two-panel design as other contenders on this list, Dropbox gets you to choose your programming language of choice first, and then provides tailored documentation for that language.

What We Love About It

We like Dropbox’s approach for its simplicity. Instead of bombarding you with information spanning the entire page, it gives you specific implementation advice for your chosen language. The lesson: cater to unique dev backgrounds.

Does It Tick the Boxes?

Authentication guide ☑
Quickstart guide ☑
Endpoint definitions ☑
Code snippets ☑
Example responses ☑

4. GitHub API Documentation

The documentation for GitHub’s REST API is also praised frequently by developers. Just like Dropbox, Github’s docs aren’t trying to put too much information on one page. The simple menu at the top-right directs developers in the right general direction, with links to reference material, guides, and libraries, and then it’s down to well-ordered, blog post-esque articles to direct developers from there.

What We Love About It

As you might have noticed, every page of GitHub’s API reference has a little widget that tells you the status of the API. It’s a small touch, but as we recently covered, small tweaks like this become very helpful. If developers are running into issues with their implementation, one glance tells them whether it may or may not be server-related. The lesson: save developer time wherever you can.

Does It Tick the Boxes?

Authentication guide ☑
Quickstart guide ☑
Endpoint definitions ☑
Code snippets ☑
Example responses ☑

5. Twitter API Documentation

Although it may not be as popular an example as the others on this list, the Twitter API documentation is one of my personal favorites on a visual level. The single container design, like with Dropbox and GitHub, directs all your attention to one place. However, the Twitter API docs feel less like a mundane blog post, and more like an interactive guide — there’s a quick note of how many minutes’ read the page is, you can switch between different methods within the post, and the concluding “Next Steps” heading is always pointing you in the right direction.

What We Love About It

The Twitter API docs have a FAQ (Frequently Asked Questions) section for almost every page. Instead of bundling too much secret information into the main explanation, all the most common questions are in those FAQ pages. Personally, I love working with a FAQ where I know I can find answers to my inevitable questions. The lesson: be flexible with how you present information.

Does It Tick the Boxes?

Authentication guide ☑
Quickstart guide ☑
Endpoint definitions ☑
Code snippets ☑
Example responses ☑

Final Thoughts

There you have it: five examples of excellent API documentation, with unique or particularly well-executed features for each. Of course, these API docs have a lot more going for them than what they’ve discussed, but you need to read our article 7 Items No API Documentation Can Live Without if you want to get the rundown on all the core features you need for great API docs.

Thomas Bush

About Thomas Bush

Thomas Bush is an enthusiastic freelance writer from the United Kingdom, who loves breaking down tough topics into bite-sized articles. Covering everything from cryptocurrencies to medicine, and now APIs, you can find out more about Thomas on LinkedIn or on his website at http://thomasbush.co.