You know what an API is, particularly what a REST API looks like.
Here, we will be relating to REST APIs.
There are a variety of tools that help automate API documentation such as Postman or Swagger. You still need to “flesh it out” the generated documentation to make it both useful and readable.
REST API documentation is typically split into two major sections:
1. An introductory section that includes for example,
- The purpose of the API
- Any prerequisites such as setup considerations (including API key requirements)
- The base URL to use
- Paging considerations for APIs with a large amount of output
- Result codes (the most common being 200 – success and 40x – errors of various types)
2. The API itself.
The API may be split into several major functionality groups each having their own endpoint and calls (GET, POST, PUT, PATCH, DELETE etc).
Each call typically requires two tables, one explaining the query parameters and a second for the results. The request parameters may be entered directly, or through an input JSON file. They are described in the first table. Very often the results come in a JSON file the fields of which are described in the second table.
Following the request/results section, add a return codes section. Always show the 200 and 400 return codes. If other possible return codes are standard, then a cross reference to the Common return codes will do. If you are using call specific return codes, add them here.
And finally, provide an example. Many modern API documentation pages have a vertical bar to the right that shows a sample of the API call in a choice of multiple formats (cURL, PHP, JavaScript etc). Other possibilities are a horizontal code bar below the API description or a link to an API sandbox. If for some reason, these features are not available, then at least, add a textbox with a hard coded example.
And there is room for flexibility: A call with a single simple parameter obviously does not need the first table. Similarly, the second table will not generally be required for POST and PUT calls.
Take a look at some of these API documentation examples:
Twitter API
Dropbox API
YouTube API
Top comments (0)