Search results

Activity: Evaluate API reference docs for core elements

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

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 either critique or create your own API reference topic for the open-source API project you identified earlier.

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. From this list of about 100 API doc sites here, identify three API documentation sites.
  2. In each of the doc sites, look for the API reference documentation section (the list of endpoints).
  3. In the reference documentation, identify each of the following sections:

    (The section names may differ in the API doc sites you find, but they’re usually recognizable.)

  4. 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, and request body parameters) for the endpoints?
    • Are the data types (string, boolean, etc.) defined for each parameter? Are max/min 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?

Create or fix an API reference documentation topic

This part of the activity might be more difficult to do, but here is where you’ll start building some examples for your portfolio.

  1. Identify one of the API reference topics that needs help. (If the API has a new reference endpoint to document, focus on this endpoint.)
  2. Edit the topic to improve it. (If it’s a new endpoint, write the documentation for it.)
  3. Create a pull request and contribute your edits to the project.

Next steps

Now that you’ve had your head buried in API reference documentation, it’s time to dive into testing. As you work with API endpoints and other code, you’ll need to test these endpoints yourself, both to gather and verify the information in your documentation. Testing isn’t always straightforward, so I devote an entire section to this topic. Continue to Overview to testing your docs.

34% Complete

34/110 pages complete. Only 76 more pages to go...

Donate?

Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.