https://www.techtarget.com/searchapparchitecture/feature/Explore-API-documentation-basics-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.
Documentation is the principal source of information about an API. Documentation covers:
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:
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:
exampleWeather?system=imperial&temp=76&wind=NNW&speed=12
exampleWeather?system=metric&temp=24&wind=NNW&speed=18
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 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.
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:
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.
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.
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.
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.
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.
29 May 2020