API Documentation – the Basics

There is no one-size-fits-all solution for creating Application Programming Interface (API) documentation; however, there are common elements in most API documentation that should be considered when creating a template for your API reference documentation. Below is a list and the suggested organization of the information commonly found in API reference documentation.

• API Object/Resource Name and Description: This contains information returned by the API and is brief (1-3 sentences). If the expected audience includes users that are not as technical as developers, then a more detailed Overview can be included before or in place of the Object Description. If the audience is primarily developers, then brevity is key and sentence fragments are acceptable in descriptions (avoid using adjectives and adverbs).
• Authentication(if required)
• Endpoints and Methods: Endpoints document how to access the resource (API URL) and methods document allowed interactions, e.g., GET, POST, PUT, DELETE.
• Request Parameters/Attributes: Endpoint options, e.g., response format or amount returned. Types of parameters include field name, type (string, int, Boolean, decimal, etc.), required vs. optional, minimum/maximum values, description, etc.
• Request Example: A sample request using the endpoint showing some parameters configured. Includes code samples.
• Response Example: A sample response from the Request Example. Includes code samples.
• Response Parameters/Attributes: Lists all possible properties that can be returned by Response, including data format, values, structures, and descriptions.
• Errors: A list of all errors that can be returned for this method. Includes error (status code), error level, cause/description, and solution/workaround.
• Use Cases (optional):  These are usually included if the audience includes business analysts and users other than developers.
• Terms of Use (optional): These are often links to a separate document/site.For web output the Terms of Use is usually included in the Introduction or Getting Started section.
• See Also (optional): Cross-reference to related API resources.

Note: Endpoints and Methods, Parameters, and Response Schemas are typically presented in tables for print and web output documentation. Request and Response Examples often have an elements table following the code sample.

API Documentation – Best Practices

• Each API resource name should be the heading at the top of the reference page. For print output, each API resource is started on a new page. For online documentation, each API resource should be its own topic.
• Authentication is often included as a separate topic because it generally applies to all APIs in the documentation. When a specific API resource has its own authentication and/or authorization requirements, it is important to include that in the topic for that API.
• A “Getting Started” guide is often included in an introductory section, along with other common topics, such as Terms of Use, Authentication, Versioning, FAQ, Tutorials, etc.
• It is common in some API documentation to provide, in the introductory section, a comprehensive listing of all error codes as a reference.

Perhaps most importantly, always ask the following questions: What kind of API is this? Is this a web service API or web API? Generally, the audience for web service APIs is almost all developers, while web API documentation is more often used by business analysts, data analysts, and program managers, in addition to developers. This, of course, leads to the one of the most basic principles of technical writing: know your audience. In the case of API documentation, if your audience includes analysts and less technical users, then the more explanatory information you can provide about the API the better. Describe why and how a user employs the specific API. If, however, your audience is predominantly developers, who mostly use the documentation solely as a reference, know that they do not need a lot of description and explanatory prose, which only makes the documentation less usable for them.