A Quality Checklist for API Documentation

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

Source

Dropbox API

Source

YouTube API

Source

API documentation – A deeper look

Anatomy of a REST API call

A REST API call consists of four main parts:

• An instruction (or verb) such as GET, POST, PUT, PATCH, DELETE etc
• A server URL like https://some.server.com
• An endpoint (or path) like /data/of/interest
• A request, following the endpoint like ?zip=12345&units=metric

A complete call will look like something this:

GET https://some.server.com//data/of/interest?zip=12345&units=metric

It is very unlikely that you will ever need to write or document an API call in this form. There are a variety of GUI tools that enable you to enter the API call components in a form. They generate the API call and provide sample code snippets (Python, JavaScript, C++ etc.) that can execute the call. For example, take a look at:

• Postman
• Swagger
• Stoplight

Some of these will generate a documentation page for your API. If you are comfortable with the command line, look at the curl command – cURL. It is available on all mainstream OSs (Windows, Unix, Linux, MacOS). The curl command is also generated by most API documentation tools along with the code snippets.

Input

As an alternative to providing lengthy request parameter lists, a tool like Swagger will help you encode your request parameters into a JSON or YAML file that becomes the request input.

The JSON encoding should follow the OpenAPI Specification that standardizes the way API call are made. (See also, The OpenAPI Specification Explained.) Following the OpenAPI spec, enables automatic generation of baseline documentation as mentioned above.

The OpenAPI standard does not specify detailed data field formats such as dates times etc. These will generally be dictated by programming context for the API. JavaScript for example, has a Date class that specifies date and time formatting.

Output

Output from an API call can be very idiosyncratic, although the tendency today is to provide output in JSON format. The required output details are also specified as fields in the input JSON file. The output can be very long and may need to be paged via successive API calls. Here is a site that does this: Webz.io API.

Return status

The most important return status codes are 200 – success and 4xx – some kind of error. A complete list of return status code can be seen here: HTTP Status Codes. Check with the API developer to ensure that these codes are being used in a standard way.

Webhooks (reverse or push APIs)

Imagine that you need to get back data repeatedly – say an hourly weather report or short messages, like WhatsApp or Twitter. One method would be to put a GET request into an endless loop. That is poor programming. The modern solution is to use a webhook (or callback) that enables the server to push data back to you as it becomes available. The server sends your browser asynchronous POST requests. See for example, What is a webhook?

What happens if your API documentation is poor

• Developers cannot find what they want and get frustrated!
• Developers find what they want but it is lacking in detail.

Poor documentation may be plagued by –

• Inadequate or missing examples.
• No use cases.

All leading to –

• Slow onboarding of new users
• Too many support-tickets (Well, at least see the Jira API Reference!)
• Customer churn (worst of all).

Also Read : Swagger API: How They Work & What you Need to Know

Ensuring API documentation quality

Finding things

Assuming we are in the API owner’s website, how do you search for the API you need? This time, Google is not the answer.

The key is to set up your metadata correctly for each API article. Use the Settings>SEO field:

If you add sufficient and salient keywords, the API user should be able to find what he need in a single use of the Search bar in the main window.

Accuracy and completeness

During the preparation of API documentation, run each API to confirm that it behaves exactly as documented. Also ensure that there are no “missing bits”: You may assume that the API user is a competent engineer, but do not assume that he can “read between the lines”. It is better to be more explicit than less.

Readability

Text

Your job is to enlighten the reader – not put him to sleep. So: Where text is required, avoid long multi-screen paragraphs. Do use short sharp sentences.

Tables

Tables are ubiquitous In API documentation. You need to give careful thought to table layout. Since for most part, API documentation is online, extremely long tables are possible.

These occur when documenting JSON file output fields. If you can, “freeze” the heading row (and maybe left column) of the table, as you might in Excel or Google Sheets.

Some users require PDF documentation: For them, try to ensure that tables are not excessively wide on screen so they look reasonable in PDF.

Simplicity

Keep it simple – but not at the cost of compromising accuracy and completeness. Taking simplicity too far can border on the offensive to a competent engineer.

Good Use Case references

Good Use Case references are the API display case. If the API is new and there aren’t any Use Cases, then you will have to compensate with additional examples. Here, an API sandbox is essential.

Additional references

Additional references for background information about the API and its use can be helpful.

Read more:  REST vs. SOAP: What is the difference?

Schedule a demo with one of our experts to take a deeper dive into Document360

Book A Demo