8 Examples of Excellent API Documentation Posted in Marketing Thomas Bush Nordic APIs May 10, 2023 Developer experience (DX) is really important these days. Creating a smooth and enjoyable experience for those implementing your APIs is essential to keep up with the competition, and excellent API documentation is one of the keys to success. Recently, we’ve discussed some examples of great developer experiences and reviewed some helpful DX tools. Below, we’ll dive head-first into the nitty gritty of it all and look at some examples of excellent API documentation. These API reference docs are great for many more reasons than one — let’s see why. 1. Stripe API Reference We challenge you to find a discussion about the best API reference docs that doesn’t include Stripe. 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 that you can copy and paste 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. Also read: 10 Tips For Writing Great API Documentation 3. Dropbox API Documentation The Dropbox API documentation is yet another example of excellent reference documentation. Instead of using the same 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 allows you to select from pre-built components, API references, and SDKs in the language of your choice. 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 ☑ Also read: 7 Tips on How to Navigate API Documentation 5. OpenAI API Reference OpenAI, the company behind the popular ChatGPT AI, also has an API. This means that developers can program advanced generative AI into their own applications. OpenAI separates its content into documentation and API reference. The documentation provides more general getting started information, and the reference digs into specific API calls. For example, a GET request to https://api.openai.com/v1/models will return a JSON-formatted list of the current models available. What We Love About It OpenAI is advanced, with various AI models for things like chat completion, speech-to-text, image generation, and more. There are also many nuances in rate limiting and pricing for each type of API request. Yet, the OpenAI knowledge center successfully onboard engineers with helpful guides for each area, and provides official bindings and libraries to jumpstart API usage. The reference is also complete with many code snippets and example responses. The lesson: organize information effectively and help developers get started quickly. Does It Tick the Boxes? Authentication guide ☑ Quickstart guide ☑ Endpoint definitions ☑ Code snippets ☑ Example responses ☑ 6. Plaid API Documentation Another stellar API documentation example is Plaid, a financial API that enables developers to integrate banking data and automatically conduct payments. Plaid provides a sleek API portal with helpful information about parameters and sample requests across all endpoints, making integration seamless and self-service. What We Love About It Plaid has an excellent content organization for its API reference materials with getting-started guides that cater to specific developer journeys. Like OpenAI, its documentation clearly organizes its reference by function with a lefthand navigation. Plaid also gets a special shoutout for its AI chatbot Bill, which accepts natural language prompts to help developers learn about how to use the API. The lesson: consider integrating AI assistants to enhance the developer experience. Does It Tick the Boxes? Authentication guide ☑ Quickstart guide ☑ Endpoint definitions ☑ Code snippets ☑ Example responses ☑ 7. Nylas API Docs Nylas provides a suite of communication-related APIs, including an email API, calendar API, scheduler API, and more. Even though Nylas’ platform caters to various functions, it is well-constructed with specific “quickstarts” for each area, which help developers quickly configure, authenticate, and send requests. What We Love About It Nylas makes our list of good API documentation examples for several reasons. First, the API reference is clear and transparent. It has a public OpenAPI file and a Postman Collection. But most of all, its public API documentation considers the developer’s journey with unique flows. The lesson: create individual quickstart guides if you have a wide product portfolio. Does It Tick the Boxes? Authentication guide ☑ Quickstart guide ☑ Endpoint definitions ☑ Code snippets ☑ Example responses ☑ 8. Shutterstock API Documentation Lastly, check out Shutterstock’s Documentation for another solid REST API example. Shutterstock’s API allows developers to programmatically retrieve content from its vast library of images, video, and music. The API reference is plainly laid out, offers a tutorial, sample requests, an SDK and CLI, and provides a live testing ground. What We Love About It Shutterstock API won our best public API of 2019 award, which should be a good indicator of success. Shutterstock adopts many of the same tips from the above APIs. One unique thing is the Shutterstock API Explorer. This explorer provides a live testing environment based on Swagger that helps programmers construct and send API requests. The lesson: allow developers to easily test requests within the docs. Does It Tick the Boxes? Authentication guide ☑ Quickstart guide ☑ Endpoint definitions ☑ Code snippets ☑ Example responses ☑ Final Thoughts There you have it: examples of excellent API documentation, with some particularly well-executed features for each. Of course, apart from following API documentation best practices, these API docs have a lot more going for them than what they’ve discussed. Your API documentation should also consider things like consistent naming, error code definitions, and human-readable descriptions. It’s also good to consider other perks to enhance developer experience wherever possible. Since it’s original publish date, this post has been updated with additional examples. The latest API insights straight to your inbox
