API documentation is familiar to programmers, dealing with it almost every day. In most development teams, API documentation exists as a bridge between the two sides, as long as there is front-end and back-end cooperation. API documentation is a back-end description of the services to be provided, and front-end developers are often the consumers of API documentation. Let me talk about what kind of API documentation is useful from a consumer’s perspective.
What is an API document?
Simply put, it is a clear explanation of all API calls and the parameters involved. Specifically, what each API can do and an explanation of each parameter in the API, including their type, format, possible values, validation rules, whether or not they are required, and so on.
What’s in the API documentation?
The welcome page
Often ignore the importance of this page, of course, if it is within the project, the welcome page sometimes isn’t that important, but if the API documentation is external, open platform, for example, every company documents, then a detailed welcome page can even decide whether a developer would like to access your platform.
The welcome page can contain:
- What apis does the product provide and what can you do with them
- How does the API work, a brief introduction to the technical architecture
- Beginner’s guide, from scratch to the establishment of a usable API call process steps, including setting up accounts, setting up the development environment, authentication, the actual operation of several aspects
(Spotify’s API documentation welcome page)
Examples containing full context
Imagine reading API documentation. Would we start at the beginning like a novel? Most of the time, we don’t. We’ll go from the API list to the API that we want to look at to read it. Therefore, for the organization of content, all necessary information and related explanatory notes should be included in each API explanation. For example, the section Commits in the GitHub REST API document, a section of each API, describes in detail:
- Return value, path rule, parameter description (parameter name, type, and description)
- Examples of input parameters
- An example of a return value
- For some specific concepts, jump links are provided for easy viewing
Common types of examples
- Examples of automatically generated code
Tools such as the API Blueprint allow you to generate sample documents directly from your project’s code. The advantage of this method is that when the source code is modified, the document content is also updated, avoiding the problem of late document update. However, it is recommended not to rely entirely on automated tools. After the content is generated, you still need to manually add necessary instructions to make the document content more understandable.
- The sample project
Nothing is more intuitive than the application of the API in a real project, with real example project code to help users understand how each API is used and how it relates. A link to the GitHub repository for the sample project can often be included in the document, or posted directly to the document if the code is not large.
- Support for multilingual client modules
As the name implies, API calls, including authentication and configuration, are encapsulated in client modules, and users can directly reference and call the encapsulated methods in the project. This method can simplify the work of the client to call the API, but it will increase the workload of the API provider. When the back-end service is updated, the client module also needs to be updated synchronously. GitHub, for example, offers client modules for different languages.
Error information
In addition, when errors occur during debugging, detailed documentation of error information can make it easier to resolve errors. It should include:
- Error status code and description
- Cause of error
- How to resolve errors
In fact, there are far fewer documents that do this. GitHub’s API documentation is fairly generic, and the context. IO documentation does a better job of error messages as a reference.
Topics related to global content
This refers to things that are common and necessary to any API document, including:
- Quick start guides and tutorials
- Information about permission authentication
- HTTP request mode and error handling
The content of these sections will vary according to different back-end services. In addition, when concepts related to these contents appear in each specific API explanation, links to specific chapters can be provided so that developers can jump to them at any time.
Some usability recommendations
API documentation can provide small features to improve the user experience. For example, the copy code button is set next to the code example to facilitate the user to copy the code with one key. Provides multi-language support for API invocation code examples. Users can view API invocation examples in different languages. With the replication function, the workload of writing duplicate codes is reduced.
What does an API document look like?
A good API document, in addition to being reasonably detailed in content, should also be simple to use in style and interaction. Nowadays, API documents are basically presented based on web pages. There are some common design methods to take advantage of the display features of web pages. Here are some best practices recommended as elements of API documentation presentation.
- Single page form
As long as the API document is not particularly large, it is recommended to display it in a single page, and it is very fast to find anything in a single page (whether it is a browser web search or a document provided navigation), plus it is easy to share the location of an API record by setting anchors in the page. Of course, if the CONTENT of the API document is too much, forcing it into a single page will affect the page experience, so you should split the document decisively, but remember to keep the global navigation information in each sub-page, so that users can easily jump from page to page.
- Fixed navigation bar
In the process of using API documents, the navigation bar fixed in the page is very necessary because the contents need to be searched frequently. Users can use the navigation bar to find the contents of the document at any time.
- Multi-column layouts
Since you use a fixed location navigation bar, it makes sense to use a multi-column layout. On a widescreen desktop web page, a multi-column layout is a good way to organize the content of a document, with one column for navigation, one column for API instructions, and one column for code samples.
API documentation maintenance
API documentation should be maintained as if it were a standalone project, with each update in the form of a pull branch, reviewed by project members after the editor has checked the content for correctness and brevity.
Post-maintenance is equally important after API documentation is published. There are two main aspects:
- New and obsolete features. Release documentation before releasing new features and ensure that the documentation goes through the standard review process. Deprecated functions should be removed from the document, and it is recommended that the deprecated functions and upgrade guide be provided in the corresponding location for the convenience of the developers who use the old functions to upgrade.
- Reserve the contribute entry for the document on the document page, and if the document is hosted on a platform like GitHub, provide a link to the repository so that every user who reads the document can Issue or PR it. If the document is closed source, there should be at least a place to provide feedback.
These are some ideas and suggestions for writing friendly API documentation for project development collaboration.