1. I'd Rather Be Writing
2. Docs
3. Chapter 3: Documenting API endpoints

Activity: Evaluate API reference docs

Download PDF

After completing the API reference tutorial, you’re ready to start an activity that gives you more experience in creating and editing API reference documentation.

In this activity, you’ll evaluate some API reference topics to identify issues.

• Activity: Evaluate API reference docs for core elements
• Next steps

Activity: Evaluate API reference docs for core elements

In this activity, you’ll review API reference documentation and identify the common elements. To evaluate the API reference docs:

1. Choose three of the following sites. In the three you choose, analyze the API reference sections (where the endpoints are listed):

   • Nexmo API reference
   • Twitter API reference
   • Stripe API reference
   • Azure API reference
   • Flickr API reference
   • YouTube API reference
   • Splunk API reference
   • Paypal API reference
   • Basecamp API reference
   • OpenSecrets API reference
   • Dropbox API reference
   • DBS Developers API
   • Adyen Docs
   • NBG Technology Hub

2. In the reference documentation, identify each of the following sections (if they exist):

   • Resource description
   • Endpoints and methods
   • Parameters
   • Request example
   • Response example and schema

   The sections might be named differently in the API doc sites you browse, but they’re usually recognizable to some degree (if included). If you’re finding it somewhat difficult to locate them, this is part of the wild west of terminology and organization when it comes to API documentation.

3. Assess the API reference documentation by answering the following questions for each section:

   Resource description:

   • Is the description action-oriented?
   • Is it a brief 1-3 sentence summary?

   Endpoints and methods:

   • How are the endpoints grouped? (Are they listed all on the same page, or on different pages? Are they grouped by method, or by resource?)
   • How are the methods specified for each endpoint?

   Parameters:

   • How many types of parameters are there (header, path, query string) or request body for the endpoints?
   • Are the data types (string, boolean, etc.) defined for each parameter? Are required/optional values noted?

   Request example:

   • In what format or language is the request shown (e.g. curl, specific languages, other)?
   • How many parameters does the sample request include?

   Response example:

   • Is there both a sample response and a response schema? (And is each element in the response actually described?)
   • How does the doc site handle nested hierarchies in the response definitions?

Next steps

Now that you understand the essential sections to cover in documenting API endpoints, let’s look at standardized approaches for describing these sections, primarily with the Overview of REST API specification formats.

The OpenAPI standard will help make sure you cover all the necessary details in these sections, and it will present the information to users in a way that users have become accustomed to.

About Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.