How to Write API Documentation: Best Practices and Examples

APIs make the world go round. Developers use APIs almost every day — by some estimates, they spend a whopping 10+ hours a week working with APIs. This covers not only using them, but also researching, googling for support, studying reviews, and of course, rummaging around in the documentation. How clear, easy, useful, and supported your API is determines the whole developer experience (DX) — an emotional response devs have to the product. In the API economy, great developer experience is fundamental. APIs that help developers succeed and are a joy to use will get tons of users and rise above the competition. And it starts at the exact moment they open the documentation for the first time.

Watch this video for an introduction to the API technology

Today we will talk about how to foster positive developer experience in the API documentation. But first, we need to understand what makes bad API docs.

What Developers Hate in API Documentation

It’s not written using simple human language. This is a common problem for auto-generated docs or docs that are neglected by creators. Although many documentation generation tools are doing a great job at commenting on the code, they cannot replace actual explanations in English written by a developer or technical writer.

It has very few code samples. This is another end of the spectrum where explanations are abundant, but there are minimal examples of the actual code.

It’s available only to registered users. This not-so-slick maneuver does nothing for your marketing. It only frustrates the people who want to know what your API does before deciding if they want it (as any sane person would).

It’s too long/can’t be found/inaccurate/hasn’t been updated in years, etc. Creating good docs is almost as important as building a good API. Because poorly written docs or the ones that can’t be found by simply googling “Product API” are failing the whole development effort. If you’re interested, we’ve already outlined specifics of technical documentation in general. But API docs deserve a dedicated article. So how do you write great API docs?

Adopt spec-driven development

An API specification is like a template of your future docs, the unified language that describes the design of your API, explains how it functions and what to expect from it. There are a few specifications, such as RAML (RESTful API Modeling Language), OpenAPI (formerly Swagger), and API Blueprint, but there’s a trend going on for combining all specs under the hood of OpenAPI.

These specs have prebuilt documentation tools that allow for writing and managing your docs. For example, API Console automatically generates docs from RAML and OpenAPI formats and helps you run it on your existing web application or as a standalone app.

API Console lets you build a web portal for your API docs from RAML and OpenAPI specifications
Pawel Psztyc

Alternative to traditional API doc solutions like WordPress or Drupal CMSs, API spec products are open source, created by the dev community for the dev community, have parsers in different programming languages, and constant creator support.

Write for the entry level

An API as any software product is created for a specific audience. But the audience for documentation is vast. There are three main groups of documentation users:

  • developers who will intimately interact with the docs
  • decision-makers like CTOs and solution architects who want to determine whether your API will be a good fit quickly
  • observers like journalists, tech writers, and even competitors who won’t necessarily use your API ever.

And even within each of these groups, there are people of different skills, roles, and needs, and all of them should have a positive experience with the docs. How do you target them all? By targeting the least experienced users. So, how do you write docs for a newcomer?

Start with the opportunities rather than technicalities. Greet users with a compelling story telling how your API can enrich their product or make developers’ lives tenfold easier.

Amazon Alexa API docs start with explaining what Alexa does and what benefit it can bring to the client

Show where to start. API docs are notorious for being too overwhelming and assuming that users have vast experience with APIs. The getting started section is obligatory, and it should be written with patience for a potential user.

Facebook provides a clear reference for beginners and follows the getting started process step by step

Create instructions for the most common use cases. You probably already know what functions people use your API for. Create separate sections addressing them and include sample messages there.

Use a conversational tone. The developer community is laidback and informal, so they won’t appreciate dry corporate language even if it sounds more “professional.” Good docs always talk to humans.

Educate on external tools. If your API requires the use and understanding of third-party products and concepts like OAuth or npm, include links to docs or installation guides.

Make it easy to learn. API docs are not IKEA assembly instructions,;they are the learning source. Enrich your documentation with FAQs, tutorials, blogs, and even videos when possible.

Incorporate must-have sections

SmartBear surveyed 3,000 API practitioners

Examples. Examples are usually presented as pieces of code, which are useful enough but can be made even more practical. For example, including a transcript of fields like it’s done in Medium docs or even creating a mock API for developers to test and use by making real calls. Mock APIs can be easily shared via a URL or on GitHub, and if done to a certain level of detail, even used in the final product.

Status and errors. There are standard status codes and those specific to your API ones. It’s a good idea to include all errors that can be triggered by your API. Errors are often put on a dedicated page of the docs, but it makes sense to duplicate some of them directly under the endpoint where they surface the most.

Authentication. Most API docs start with authentication and authorization. It should cover info on how to get an API key and how to authenticate requests, including possible errors, token expiration times, and an explanation on authentication sensitivity (basically reminding that keys can’t be shared, and where they can be used).

HTTP requests. Providing web requests in HTTP is the bare minimum for documentation. It’s usually assumed that devs will know how to send HTTP requests in their language of choice, but sometimes, API creators include requests in various languages. This can be done automatically via API spec tools and API management tools like Postman.

Use industry-standard layout

Dynamic layout. You can recognize an outdated API by its static documentation. A single page or even a PDF document doesn’t cut it in 2020. Dynamic docs are easy to look through, update, and bookmark.

Sticky contents. No, the navigation bar doesn’t distract nor does it steal precious screen space. Always keep the contents in sight.

Three-column layout. Not used very often, this layout allows you to have another column on the right for the code examples. Of course, this only makes sense if you have a ton of text and want to highlight code so that users don’t have to scroll back and forth or switch between tabs.

HubSpot API docs use a three-column layout

Use contrast colors for syntax. Developers spend a lot of time looking at your code examples, so make them readable and separate different components by color.

This example from Facebook’s Graph API docs also shows how you can use different tabs to choose between SDKs

Saved scroll state. This is a small detail that any developer will appreciate. You can also use anchor links to specify different sections of the page in case they copy the URL.

Encourage feedback. Your docs are your main marketing tool — if people love them, they will use your API over competitor’s and drive the community around it. The usual “Was this page helpful?” message will let you know how well you’re addressing devs’ questions and the feedback form will be used often as long as you deliver on it.

Don’t abandon your docs

Prepare docs prior to the updates. Make it an additional step in your launch plan, don’t roll them out before you have well-written, detailed, and edited paragraphs to introduce your updates.

Regularly remove deprecated data. The docs have to be reviewed often, at least once every few months. User feedback features will let you catch inconsistencies earlier and there should always be a team member responsible for reviewing them and reacting to updates.

Use analytics to improve docs. Standard API analytics will tell you which endpoints are used more often, so you can focus on certain parts of documentation and provide more useful info or create dedicated tutorials. Monitor the use cases your APIs are used for because that will let you widen the value proposition and update the docs with more possibilities.

Great API documentation examples

Medium API documentation

Mailchimp API documentation

  • what an endpoint does and what the guide will let users do
  • what you’ll need — any accesses or accounts a user must get first
  • what each function is with a text description, a code example in several languages, and sometimes screenshots of the interface.

There’s even a copy button for each piece of code — a detail that non-techies will certainly appreciate.

Twilio API documentation

Spotify API documentation

Treat docs with care

Originally published at AltexSoft tech blog “How to Write API Documentation: Best Practices and Examples

Being a Technology & Solution Consulting company, AltexSoft co-builds technology products to help companies accelerate growth.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store