Search results

Activity 3b: 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. 5,000+ subscribers

I'm giving an API documentation workshop in San Francisco, California, on November 19, 2019. Check it out on EventBrite and register today to receive a $100 early bird discount.

Activity 3b: 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. Either from an open-source project you might have identified or from this list of about 100 API doc sites here, identify an API documentation site to analyze.
  2. In the API documentation, 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 will probably differ in the API doc sites you find, but they’re usually recognizable to some degree. 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.

  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?
12% Complete

12/146 pages complete. Only 134 more pages to go.



Donate?

Want to buy me lunch? Click the Donate button below to donate any amount through Paypal.