Explore API documentation basics and best practices
API documentation should be easy to understand -- but how do you accomplish this? Use this quick guide to learn key API documentation components, noteworthy tools and best practices.
APIs enable developers to define the interactions between software and services. But simply creating an API isn't enough. Documentation makes the difference between happy and frustrated API adopters.
A business creates an API for a given service so that internal users, business partners or even public developers can integrate their respective software with that service. One well-known example is the Google Maps API, which plays an important role in providing Google's mapping and location services to the global software development community.
The API itself isn't all those users need to get value from the service. There's a suite of available API calls or requests, syntax, conventions, data formats and other information around the API. Good documentation is almost as important as the API's underlying code. Learn the basics of API documentation and the top documentation tools used by developers, and follow API documentation best practices to maintain APIs that work well for everyone.
What is API documentation and why is it important?
Documentation is the principal source of information about an API. Documentation covers:
the features and functionality available with an API;
a comprehensive suite of feature and syntax references;
tutorials;
examples; and
access to support or additional information.
An API without good documentation can lead to frustrating and time-consuming adoption -- and potentially slow down the development and performance of applications that connect to a service.
There are three broad categories of API documentation: reference, example and tutorial.
Reference documentation covers the granular details of an API. It details the purpose, functionality and complete syntax (sometimes called schema) of every call or request that the API supports. For example, each call for an API response should provide the following details:
a description of the call or request;
a full syntax expression of the call with placeholders showing all available parameters;
a list of all parameters that can be included with the call;
a list of all responses that may be returned by the API call or request (including any error or warning responses); and
one or more examples of the call or request as it might actually be used in a program.
Example documentation uses simple illustrations in the reference documents to show numerous examples of use cases for the API. As one example, an API accepts parameters in either metric or imperial measurement systems. Example documentation demonstrates the API used in each option:
Tutorial documentation focuses on providing context for the API. API documentation usually includes a range of guides and tutorials that build on examples to offer a comprehensive discussion of API usage. Tutorials and guides typically show how multiple API calls and requests work together in the context of actual code segments to accomplish tasks beyond single calls.
Additional API documentation depends on the API and users. For example, the company can include a detailed discussion of authentication factors and usage, legal information about terms of use, a detailed change log that records when calls and parameters are added or changed, or any other topics that make API use easier for the target audience.
API documentation tools
API documentation is notoriously difficult to produce and maintain. This is true for virtually any documentation, but APIs are particularly challenging because they involve countless technical nuances to which you must adhere. Minor documentation errors, such as an extra space, can make an API fail.
Good API documentation does not happen by accident.
API volume is another problem. Each additional API from an organization produces more API documentation to maintain. This fact, coupled with ever-shrinking software development cycles, leaves little time for developers to create and maintain quality API documentation.
There are numerous commercial and open source tools to automate and organize API documentation, which ensures consistent style and content. Here is just a sampling of some noteworthy API documentation tools:
Aglio renders HTML from API Blueprint files with support for custom colors, templates and themes.
DapperDox is an open source renderer for OpenAPI Specifications, offering GitHub-styled markdown documentation, guides and diagrams.
I/O Docs is an API definition format for the TIBCO Mashery network which includes a live interactive documentation system for RESTful web APIs.
Paligo helps authors write rich structured content with strong version control.
RAML 2 HTML is a simple documentation generator written for Node.js that converts RESTful API Modeling Language to HTML.
Redoc.ly is intended to create, style and manage interactive API documentation.
Slate helps to create static API documentation with a clean, intuitive design.
Snowboard is an API Blueprint parser and mapper.
Stoplight offers hosted, customizable, interactive API documentation automatically from the API's OpenAPI Specification.
Swagger UI is part of the Swagger framework and automatically generates documentation from the API's OpenAPI Specification.
Most automated API management tools use the OpenAPI Specification, formerly called the Swagger specification. This specification outlines a standardized format to describe, produce, consume and visualize RESTful web APIs. This standardized specification helps development teams produce consistent documentation quickly and avoid mistakes that arise from manual documentation attempts.
API documentation best practices
Good API documentation does not happen by accident. It takes clear guidelines, a consistent team effort, stringent peer review and a commitment to maintain documentation throughout an API's lifecycle. Some top API documentation best practices you should implement include:
Include all necessary components. A complete documentation package usually has sections on authentication, error messages, resource usage and terms of acceptable use policies, and a comprehensive change log. Some API documentation also includes a series of guides that provides detailed examples of API use and use cases.
Know the intended audience. Tailor API documentation for the intended audience. If the documentation is intended for novice developers, focus on things like tutorials, samples and guides. If the documentation is intended for experienced developers, build up reference material detailing syntax, parameters, arguments and response details.
Consider how to include vested non-developers, such as project managers or even CTOs, in the API documentation. Those titles want to see high-level overviews of the API's purpose and capabilities, as well as the legal issues outlined in a terms of use section.
Assign responsibility for documentation. One or more members of the development team should develop and maintain the API documentation to ensure its accuracy, clarity and ease of use. It may not warrant a full-time job, but even the finest API documentation tools can benefit from a person's input, adding notes, examples and other essential components. Give this responsibility to someone who can collaborate with other departments, such as engineering, product development, marketing and legal to make the documentation accessible.
Look for balance in the coverage. Syntax references, examples and guides create the technical heart of API documentation. Review this documentation for even and consistent coverage. For example, the syntax reference should be about the same length -- and include the same elements -- for every call or request. If one function is detailed over five pages, and another function only half a page, the documentation may be incomplete. Similarly, watch out for examples that only showcase a small portion of the API calls, or neglect to address responses such as error messages.
Bring documentation into the development process. API documentation is generally better when it's included as part of the iterative development process. For every new release, the documentation should be updated and changed accordingly. Treating API documentation as an afterthought or separate task will lead to neglect, oversights and disconnection from the API's users. It takes time and effort to create comprehensive API documentation, but the investment is worthwhile. Absent, incomplete or inaccurate API documentation can make API management impossible.
Examples of API documentation
Below are some examples of how to organize and present API documentation for various services.
API management tools can often assist with automatic API documentation, automatically producing details for each call, code examples and other common elements. Automated documentation helps to bring consistency and completeness to large and complex technical documentation projects.
The example below shows RESTful API documentation for Cytomine, an open source web tool that uses machine learning to process and analyze images. Through a browser, users can view documentation for various services and directly test API responses in a playground area.
Example of API documentation for Cytomine, an open source image processing tool.
References are essential parts of API documentation, which includes a complete list of calls along with carefully documented syntax, parameters, arguments and messages.
This image shows API documentation with references for the Box content management system.
BoxDev API documentation.
API documentation can organize calls by type or purpose, allowing users to find desired content more easily based on programming goals.
This example shows API documentation for Wavefront, a VMware cloud monitoring tool. The documentation is generated by Swagger.
REST API documentation for VMware's Wavefront cloud monitoring tool.
