API Reference Overviews

Overviews, or descriptions, are crucial parts of every API reference documentation. However, a common challenge in writing an overview is deciding the right amount of content. How much is enough? What should be included or excluded? Should the overview be detailed or brief?

To answer the questions above, I reviewed several API reference websites to see how their authors approached reference descriptions. This write-up details my findings, alongside some best practices for writing effective API overviews.

What is an API Reference Overview?

In technical documentation, reference overviews are used to summarize an API’s functionality. They help developers—the primary consumers of reference documentation—and other stakeholders understand the role of an endpoint or group of endpoints. API overviews and API descriptions refer to the same concept and will be used interchangeably in this report.

Types of API Reference Overviews

Reference overviews can be categorized into three types: high-level, group-level, and path-level overviews. Let’s explore each of these.

1. High-level Overview:

   This is a summary of all the endpoints in an API. It often provides information about the API’s underlying technology, how to structure requests, the expected response format, authentication details, available environments, and how to get started, among other things. Stripe’s API contains a perfect example of a high-level description. Here it is below:

   

   This description provides a snapshot of the Stripe API and how users can start interacting with it.

2. Group-level Overview:

   This summarizes endpoints that perform related functions. For example, in Mailchimp’s API, the Automations group—which includes endpoints like List Automation, Add Automation, Get Automation Info, and others—illustrates a group-level description.

   

   The description above clearly indicates what can and cannot be achieved with the endpoints within this Automations group. The use of group-level descriptions depends on the structure of the API being documented; some API documentation sites may not include this category of reference overview.

3. Path-level Description:

   This describes a specific endpoint or path. Here’s an example from X’s API:

   

   The path-level description in the image above conveys what to expect from the /2/tweets endpoint.

The three categories of reference overviews outlined in this section play different, but critical, roles in communicating the purpose of an API to its users. In the upcoming section, I will present the findings from my research on how reference descriptions are utilized across various documentation sites.

An Analysis of Selected API Overviews

I examined twenty different APIs to see how reference overviews were implemented. In this section, I will detail my selection criteria, present the results obtained from the chosen samples, discuss the inferences drawn, and outline the challenges encountered during the analysis. First, the selection criteria:

1. Selection Criteria

To streamline the process, I based my selection of samples on the following criteria:

1.1. High-level Descriptions

• The API documentation must have a straightforward information architecture.

• A high-level description should include any or all of the following: the API’s underlying technology, request and response formats, minor authentication information, available environments, endpoint organization, and how to get started.

• The information listed in point 2 must all be on one page but can be divided into separate sections.

• Detailed authentication instructions should not be considered if provided on a different page or section.

• Information about the available environment only counts if included on the overview page.

• The getting started guide should not be considered, even if placed on the same page as the overview section.

1.2. Group-Level Descriptions

• Each group must have an overview section.

• Each group must contain one or more endpoints.

• Objects with two or more endpoints are considered a group. For such APIs, only the object's overview section should be considered.

1.3. Path-Level Descriptions

• The path or endpoint must have an overview section.

• The description must be specific to a single endpoint.

• Information that directs users to additional resources about the endpoint counts.

2. Results

After compiling my samples, I used a Python script to calculate the total number of words in each API overview. This file contains the data from which the figures in the following tables were generated:

2.1. High-level Descriptions

Table 1

2.2. Group-level Descriptions

Table 2

2.3. Path-level Descriptions

Table 3

3. Inference

With the average word count for the different categories of reference overviews now obtained, I compiled the results into a single table for a more comprehensive view.

Table 4

From the table above, I made the following deductions:

• High-level API reference overviews are the longest: This is expected, as this category of overviews aims to capture the entire API and provide important information on its usage.

• Group-level API overviews have less content than their high-level counterparts: This is also expected. Group descriptions only cover a subset of endpoints that perform related functions.

• Path-level reference descriptions are the shortest: As seen in Table 3 above, a path description can be as brief as three words. This is acceptable, provided it accurately conveys the function of the endpoint.

4. Challenges

I encountered the following challenges while carrying out this research:

• There are no standard rules for structuring API reference information, which made it challenging to find samples that met my criteria.

• Some documentation sites divided their high-level overview into multiple sections and pages.

• Some API references listed endpoints without organization, while those that grouped their endpoints often lacked descriptive information for these groups.

The upcoming section will address the questions raised at the beginning of this article by highlighting the pitfalls to avoid when crafting API overviews.

Best Practices for Writing API Reference Overviews

The following are some best practices to adopt when documenting API overviews:

• Keep descriptions brief and relevant.

• Avoid listing endpoint parameters or response schemas in overviews.

• Restrict each endpoint description to that specific endpoint.

• Minimize the use of passive voice.

• Group descriptions should summarize the functions of the endpoints within the group.

• High-level overviews should include the API’s technology (REST, GraphQL, etc.), request/response format (JSON, XML, etc.), available environments (Test and Live mode), authentication information, and other key details about the API’s capabilities.

The recommendations above are non-exhaustive, but adopting them will benefit your reference descriptions.

Conclusion

APIs are unique, and their descriptions should reflect that uniqueness. My research is not devoid of flaws, so treat the information here as a flexible guide when writing reference overviews. The total word count for your overview content can vary from the figures in Table 4, provided you adequately cover what the user needs to know about an endpoint or group of endpoints.

By adhering to best practices for writing API overviews and using Table 4 as a benchmark, you can significantly enhance the quality of your documentation. This approach will help developers and other stakeholders have a seamless and productive experience with your API, ultimately leading to better adoption and fewer support issues.