How to write excellent API Documentation

From my experience of managing Application support teams, one of the key elements we always refer to is API documentation. From a production support standpoint, it is important to understand the flow, features, and functionality of the API to effectively troubleshoot. This could also avoid human errors and misconfiguration during deployments.

Well-written API documentation is a vital part of the API building process. The API documentation can be a reference, tutorial, and conceptual. Without clear documentation, your API service becomes difficult to implement and understand, deterring potential users.

One of the key lessons I learned is to plan and allocate time for documentation. It can be done parallelly but there is a good chance that you will either miss out on key points or miss your deadlines.

Few important sections for good documentation,

• Overview of the service your API provides a quick but precise explanation that lets the user know what your API does. This could be a “Getting Started” section
• Example code snippet in various languages It's good practice to provide examples in as many programming languages as possible, or at least the most used ones to demonstrate how to use them.
• Tutorial explanation Along with code snippets, provide details on various methods/parameters/resources. Include sample HTTP request and expected response
• Authorization information Provide information on how to access API credentials, keys, and tokens. Remind users of all the basic API security best practices
• Error and debugging details Include all status codes that can be returned by your API endpoints they may occur. Offer solutions to common errors.
• Links to external resources Your documents should be accessible to people of all skill levels if your API requires 3rd party tool (for example OAuth, NPM, etc.,), Provide links to educate about such external resources.

Good to have Comments Section, Frequently Asked Questions section, a Glossary and Contact section

Maintaining API Documentation

It is critical to ensure all your documents remain accurate and up to date. Outdated API documentation will let frustrated users, and increase costs as developers turn to your teams again and again for the help.

It is not hard to maintain your API documentation; you can build a process to organically have the API documentation updated. A few steps we followed in our environment helped to improve the quality of the API documents.

•  If any new features have been added to the API, ensure all relevant information appears in the document. A good practice is to release updated API documentation with each new API release.
• Update descriptions for any features that are added or removed. It is very important if a feature is removed, mention that in the document, along with the reasoning behind the removal.
• Version the API document, have a table to record historical updates, peer review and mandate API documentation before moving between environments. (Example from test environment to pre-production environment)

Avoid Overly technical writing, Large blocks of texts, Technical Jargons and most important never mention Credentials/Confidential information in the document

API Documentation Tool

The tools help to reduce the time it takes for developers and architects to write and maintain API documentation by automating or simplifying some tasks. Some of the feature that the tools support includes automatic updates to documentation based on the changes.

Here are some tools used by the team, which are common in the industry

• Postman is an API platform for developers to design, build, test, and iterate their APIs.
• Swagger hub is an integrated API design and documentation platform, built for teams to drive consistency and discipline across the API development workflow.

In conclusion, the API documentation is written by the people who have the best understanding of the API. Most of the cases it is the developers who have the best technical knowledge of the APIs. However, they might not have the best writing skills or give priority to writing a complete document. This is where the architects come in. The job of architects includes reviewing the document and also making sure the document translates complex technical subject matter into easy-to-understand explanations.

Knowing how to create excellent API documentation will ease your job.

I have shared my learning and experience on the importance of API documentation through this article with the knowledge I gained from expert architects, technical managers, and client partners. Hope this can help you create great API documentation and guide others.