How to Write API Documentation: Best Practices and Examples

APIs make the world go round. Developers and other professionals use APIs almost daily. Working with them, by some estimates, 10+ hours a week, for researching, googling for support, studying reviews, and 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 deal with 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.

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

What API documentation is and things developers hate about it

API documentation is a guide on how to integrate and work with a given application programming interface. It describes requests, responses, error messages, and other essential details.

The dev community is a passionate one. It’s specifically passionate about the things they don’t like. If they don’t like an API, it’s mostly because of junky docs, even if the product is great. Here are some common issues devs have with API docs.

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

Spec-driven development (SDD) is similar to test-driven development in which you write test cases for each feature and then code that should pass them. In SDD, you create docs or some parts of it in parallel with building an API, often following a certain API description format called a specification.

An API specification is like a template for your future API; 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, and API Blueprint. Still, there’s a trend toward 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.

We’ll touch more on specifications and tools in a bit.

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 enjoy constant creator support.

Write for the entry-level

There’s a reason technical documentation is usually not written by developers themselves – it’s the job of technical writers, experts in translating tech aspects into a readable format. But even technical writers tend to leak a bit of jargon into the text.

An API, like 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; and
• product managers, business analysts, and other non-technical specialists who evaluate the API.

Within each of these groups, there are people with different skills, roles, and needs, all of whom 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 the technicalities. Greet users with compelling storytelling about how your API can enrich their product or make developers’ lives ten times easier.

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 should be written clearly for a potential user.

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 using and understanding 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

In 2019, SmartBear, the developer of tools for API designing and documenting Swagger, surveyed API developers and users. They found what docs features are considered the most important in the community, giving us a list of the must-have documentation sections devs want to cover. We’ll go through some of them.

Examples. Examples are usually presented as pieces of code that are useful enough but can be made even more practical. For instance, include a transcript of fields as it’s done in Medium docs or even create a mock API to test it on 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. Including all errors your API can trigger is a good idea. Errors are often put on a dedicated page of the docs, but it makes sense to duplicate some 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 of 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.

Quotas and limits on requests. If you expose the API to third-party users, define how many requests your infrastructure can handle and let your customers know the limits. This transparency will prevent API overuse.

Use industry-standard layout

If you’re relying on a documentation generator, the layout is already decided. Most API docs look and feel the same. You know how to approach new docs if you’ve used a few. Still, organizing large volumes of data, making it findable and easy to navigate, is complex. Here are some features of the most functional layout.

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

Sticky contents. No, the navigation bar shouldn't distract or 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.

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.

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 prefer your API over competitors 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

Outdated docs are the biggest pet peeve of API users. This is also one of the most common mistakes. Developers often write about updates several days after rolling them out, sometimes limiting themselves to a few sentences. This happens because there’s no established process, and it’s no one’s responsibility. Here’s how to ensure regular and useful doc updates.

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

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

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 the documentation and provide more helpful info or create dedicated tutorials. Monitor the most common API use cases because that will let you widen the value proposition and update the docs with more possibilities.

API documentation templates and tools

Today, you don’t need to create your API documentation from scratch and manually if your API follows the OpenAPI specification. As mentioned, API specification is a language that allows you to standardize your web service, generate client code and even test cases. Similarly, you can employ tools to automatically design the initial version of your docs and then infuse it with details and descriptions.

Postman

Postman is one of the key tools used to build and test APIs. If you stick to OpenAPI 2.0 or 3.0, it will automatically generate documentation from the template, containing methods, requests/response bodies, examples, and parameters. Also, Postman will highlight constraints, including minimum and maximum values.

Swagger

Swagger is another popular API development tool using OpenAPI specification. In fact, OpenAPI was part of Swagger until 2016, when the specification became the brand-agnostic standard for web services. Like Postman, it automatically generates documentation based on your API definition and allows for creating this definition if you don’t have one. Swagger suggests an advanced versioning system to track your API iterations in docs.

Great REST API documentation examples

There are tons of good docs to explore and learn from. In addition to the examples we’ve shared throughout the article, here are some more for you to enjoy and take note of. All of them follow REST conventions, as this API architecture is currently the most popular for web-based APIs.

Salesforce API documentation

Salesforce Platform API (or rather a set of many APIs) is currently the world's most popular application programming interface, according to Postman. With massive integration capabilities and functionalities covered, Salesforce requires robust and approachable documentation to bring developers on board quickly. While it’s a bit of a jungle for a newcomer to find a specific API, such tools as guides, the catalog, and a search bar help a user to conquer the complexity.

Salesforce and its community keep their documents updated, regardless of the scope. Most API docs are broken down into three sections: brief informative descriptions, guides, and references with all endpoints and methods listed in the contents.

Mailchimp API documentation

Mailchimp realizes that most of its audience are marketing professionals and uses language that enables even non-tech people to understand how to work with its APIs. At a glance, each section follows the same structure:

• 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; and
• what each function is, with a text description, a code example in several languages, and sometimes screenshots of the interface.

Twilio API documentation

Twilio has famously good API docs. Although docs are just the tip of the iceberg of all the help Twilio shares – there are SDKs in several languages and sample apps for iOS, Android, and the web. First, they follow the three-column logic with the code directly on the right side of the guide. The simplest actions are explained in detail, and there are tons of links for additional information in addition to screenshots. Feedback is also encouraged via a “Rate this page” button and links to the support team and the tag on StackOverflow.

Spotify API documentation

Although Spotify’s web API docs are very typical, they have a lot of additional information in its Spotify for Developers platform. There are demos for basic functions, mock apps, live examples built using Spotify APIs and widgets, wrappers for different programming languages, and the console. The console is basically an interactive documentation where you can fill your (or sample) data in and explore endpoints live. Powerful products and a strong knowledge base make Spotify a reliable partner that developers like to work with.

Who writes API documentation?

Documentation is the only touchpoint you’ll have with most of your audience, so you need to learn to communicate clearly through it. The best tip here is to make it someone’s job. This technical writer must know how to speak to audiences of different skills, translate developers’ words into actionable points, and monitor the timely maintenance and updating of the docs. But managing great documentation is possible even without an expert on your staff. API management tools like Swagger UI, Spotlight, Apiary, and docs specification software have a broad functionality to help you make docs that developers will love.