How to write API documentation?

A Brands experience

Thanks to Boris Romero, Álvaro León, and Diego Samur for reviewing this article.

Photo by J. Kelly Brito on Unsplash

Hi 👋🏻 I’m back again with a new story about the great experience of being a backend developer at Cornershop by Uber.

I’m currently working on a project where we want to publish an API that allows our business customers to communicate with the information generated by the Brands team. With it, they can receive data to feed their decision-making dashboard or other integrations. During the design and development process, we decided to develop simple documentation to help us launch the product as soon as possible, with the goal of validating the use of our new integration with customers.

That’s why I started to do more research about this topic- mainly about what API documentation should have at a content level, with the goal of generating an initial document that is easy to access, use, and reference, to later evolve technologically to something much more robust.

Some articles I read on the internet talked about the importance of the developer’s experience when using an API. Lets remember that these will be the primary users and we are looking to develop a clear, useful, and easy-to-use API.

What developers hate in API documentation

Below you will find a list of features that, in my experience, developers hate in API documentation:

• It’s not written using simple human language
• It has very few code examples
• It’s available only to registered users
• It’s too long
• It’s not easy to find
• It hasn’t been updated in years

Main users of API documentation

Just like any software product, an API is created for a specific audience, but the audience for documentation is huge. There are three main groups of documentation users:

• Developers who will interact closely with the documents
• Decision makers such as CTOs and solution architects who want to determine if their API will adapt quickly
• Observers such as journalists, technology writers and even competitors who may never actually use your API

What features should API documentation have?

• A value proposition. Greet users with a compelling story that tells them how your API can enrich their product or make developers’ lives ten times easier
• A clear starting point. API docs are notorious for being overwhelming and assuming users have a wealth of experience with APIs. The introduction section is crucial and should be written patiently 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 that address them and include sample messages there.
• A friendly, conversational tone. The developer community is relaxed and informal, so they won’t appreciate dry corporate language, even if it sounds more “professional.”
• Clear information about external tools. If your API requires the use and understanding of third-party products and concepts such as OAuth or npm, include links to docs or installation guides.
• Make it easy to learn. Enrich your documentation with FAQs, tutorials, blogs, and even videos when possible.

Must-have sections in API documentation

In 2019, SmartBear, the developer of Swagger, surveyed developers and API users. They found out which documentation sections are considered the most important in the community and published a list of must-have documentation sections that developers want to cover. Check them out:

• Examples: examples are usually presented as code snippets
• States and errors: it’s a good idea to include all errors that your API may trigger
• Authentication: the API should cover information on how to obtain an API key and how to authenticate requests, including possible errors, token expiration times, and an explanation of authentication sensitivity (basically remembering that keys cannot be shared and where they can be used)
• HTTP requests: providing web requests over HTTP is the bare minimum for documentation. It is usually assumed that developers will know how to send HTTP requests in the programming language of their choice, but sometimes API creators include requests in multiple languages as examples
• URI Structures, Methods and Parameters: to add more value to this endpoint definition, it’s best to document the structure and methods for each URI within the API
• Getting Started Guide: an Introduction section that illustrates key information and steps for using the API. It should also include an overview of the API functionality.

The final decision

After doing the research, we decided to create documentation with similar characteristics to Medium’s documentation, this one, although simple, fulfilled what we were looking for: a simple and concise way to show the information of our new Brands API. We also kept the idea of making a technological update soon, for when we perform the testing process with some initial users.

API documentation examples

• Documentation for Medium https://github.com/Medium/medium-api-docs#2-authentication
• Documentation for Mailchimp https://mailchimp.com/developer/
• Documentation for Twilio https://www.twilio.com/es-mx/docs
• Documentation for Spotify https://developer.spotify.com/
• Documentation for Stripe https://stripe.com/docs/api

References

• How to Write API Documentation: Best Practices and Examples https://www.altexsoft.com/blog/api-documentation/
• Medium’s API documentation https://github.com/Medium/medium-api-docs#2-authentication
• 5 Examples of Excellent API Documentation (and Why We Think So) https://nordicapis.com/5-examples-of-excellent-api-documentation/
• 7 Items No API Documentation Can Live Without https://nordicapis.com/7-items-no-api-documentation-can-live-without/
• What Is API Documentation? https://www.akana.com/blog/what-is-api-documentation