by James E.
• July 13, 2020
The content, structure, and style of your API documentation will define how easy it is for your users to learn, understand, and use your API. Getting these aspects of your API documentation right will not save your users (internal or external) time and effort, reduce the strain on your support staff, and improve user satisfaction.
In this article, we’ve picked out eight API documentation examples from well-known tools that showcase best practices that you can use in your own documents. Although these API documentation examples are from large companies whose APIs are used by tens of thousands of businesses, you can apply these universal to documentation for businesses and APIs of any size and complexity, even internal-facing ones.
Did you know you can generate a full-featured, documented, and secure REST API in minutes using DreamFactory? Sign up for our free 14 day hosted trial to learn how! Our guided tour will show you how to create an API using an example MySQL database provided to you as part of the trial!
Create a REST API Now
Best in Class – Twilio
Slack’s Documentation Helps Beginners Get Started
Great Navigation with Google Maps API
How Microsoft uses a Documentary Directory to Help Developers Find What They Need
Vimeo’s Documentation Shows How to Write a Getting Started Guide
Stripe’s API Documentation Showcases Formatting Best Practice
Adding Interactivity Like SendGrid
PayPal’s Release Notes Keep Developers Up-to-Date
Managing API Documentation with DreamFactory
Let’s take a look at the API documentation examples:
[Screenshot source: https://www.twilio.com/docs/usage/api]
If you can only look at one example, look at Twilio’s API documentation. Laid out using three columns – navigation, explanation, and code – this documentation is clear, well-thought-through, and has many nice touches.
The left-most column provides a clear overview of the topics and makes finding the content you need easy. The authors have further improved navigation by using many internal links in the central column and adding a search bar in the header.
The right-most column packs in a huge amount of information. Note in the screenshot above that the sample code to POST a simple SMS using the Programmable SMS API includes code for Node.js, C#, PHP, Ruby, Python, Java & Curl, as well as a sample JSON API response. Users can select their coding language and then copy the code with one click to help them start using the code in their own applications.
[Screenshot source: https://api.slack.com/authentication]
When writing user documentation, it’s important to keep in mind who is reading it. Depending on your userbase, and whether it is an internal or external document, a beginner might mean an experienced developer who simply hasn’t used your API before, or it might include users who have never used an API before.
Slack has identified that some of their users are beginners and has written their more basic content with this readership in mind. Features include:
You’ll notice that this style does not continue for every page of the documentation. For reference pages, such as this one for the method admin.apps.approve, Slack sticks to the facts, reflecting that this page’s reader is more likely to be an experienced developer looking something up.
Busy developers want to find the information they need fast so that they can continue working on their project – and for that, you need good navigation. Google’s Google Maps documentation uses a three-column layout that focuses on providing users plenty of options to find the information they need.
As with Twilio’s API, the left-most column shows an overview of topics. However, Google puts code samples in the center column and uses the third column to provide a contents list for the article the user is reading. There’s also the Search field in the header and a dropdown menu for Documentation which lists popular destinations.
The documentation also includes a few other nice touches: we like the flask symbol given to features currently in beta, and the option to switch from a light theme to a dark code theme is a welcome bonus.
[Screenshot source: https://docs.microsoft.com/en-gb/]
As your business grows, it’s likely that you’ll need to document multiple API or other tools. As businesses create documentation at scale, navigation’s importance grows beyond finding the right article within a single document to finding the right piece amongst tens or even hundreds of different pieces of documentation.
Microsoft, for example, has a huge range of technical documentation available for developers to access, but their directory makes it easy for users to quickly drill down to the information that they need.
DreamFactory enables developers to create, manage, and automatically document their APIs in a single, well-managed location. Start your free 14-day hosted trial today.
[Screenshot source: https://developer.vimeo.com/api/guides/start]
One of the most useful parts of any documentation is the Getting Started guide. This section moves beyond documentation to offer new and inexperienced users a helping hand getting started. Alongside Slack, which we mentioned above, Vimeo is another business that offers a great beginner experience, particularly through their Getting Started section.
This has several features that we like:
Even if a business’s documentation is internal-only, and the current team is highly-experienced, it is best practice to create a getting started guide for onboarding future team members.
[Screenshot source: https://stripe.com/docs/api/authentication]
Stripe’s API documentation follows the same format as Twilio’s and offers a similarly excellent experience. It has an easy-to-read quickstart guide, great navigation, and clearly explains everything a developer might need to know.
It’s biggest strength, though, is how it displays this information. It’s design is clear and well-formatted, and manages to feel uncluttered even when delivering a vast amount of information. This design helps create a great experience for developers who use it.
[Screenshot source: https://sendgrid.com/docs/api-reference/]
Interactive features enable developers to test out code without leaving the documentation, making it easy for users to try things out and learn how they work.
SendGrid’s API documentation is a great example of this. Users can put in their API key and then test out the code and get a response. The code is editable, so users can make changes to see what effects these changes have.
DreamFactory enables businesses to automatically create fully-interactive documentation as soon as they create a new API. Click here to start your FREE 14-day hosted DreamFactory trial today.
[Screenshot source: https://developer.paypal.com/docs/release-notes/release-notes-2020/#]
Maintaining your API documentation, including adding documentation on new features and removing or flagging documentation on depreciated features, is important to ensure your resource continues to be useful to developers.
It’s a good idea to include a changelog or release notes, such as these published by PayPal for their REST API, to make it easy for users to check what has changed recently.
DreamFactory is an enterprise-grade API-as-a-Service platform that enables businesses to quickly create fully-documented REST APIs without any coding experience.
Start your FREE 14-day hosted DreamFactory trial today or schedule a call with our team to find out more.
Join the DreamFactory newsletter list.