I'm giving an API documentation workshop in Mountain View, California on August 30, 2019. If you're interested, you can register on EventBrite.
The API overview explains what you can do with the API, including the high-level business goals, the market needs or pain points it solves, who the API is for, and other introductory information.
- Purpose of the API overview
- Explain the market problems your API solves
- Sample API overviews
- Activity with API overviews
Purpose of the API overview
Too often with API documentation (perhaps because the content is often written by developers), the documentation gets quickly mired in technical details without ever explaining clearly what the API is used for. Don’t lose sight of the overall purpose and business goals of your API by getting lost in the endpoints.
The API overview grounds users with a high-level understanding of the system. This high-level understanding is critical in order to grasp the system as a whole. It allows the details to fit into a broader conceptual framework.
To get an idea of what the API is about, users start at a high-level, getting a gist of what something is about from the title and description, and then work their way into more details. This overview provides this initial orientation for the user.
For more details on the importance of high-level overviews, see Reduction, layering, and distillation as a strategy for simplicity.
In the overview, list some common business scenarios in which the API might be useful. These scenarios will give users the context they need to evaluate whether the API is relevant to their needs.
Keep in mind that there are thousands of APIs. If people are browsing your API, their first and most pressing question is, what information does it return? Is this information relevant and useful to my needs?
Explain the market problems your API solves
In The Top 20 Reasons Startups Fail, one of the main reasons startups fail is their inability to solve a market problem. The authors explain:
Startups fail when they are not solving a market problem. We were not solving a large enough problem that we could universally serve with a scalable solution. We had great technology, great data on shopping behavior, great reputation as a thought leader, great expertise, great advisors, etc, but what we didn’t have was technology or business model that solved a pain point in a scalable way. (CB Insights)
This overview focuses in on the market problem that the API solves. If your API fails, it’s likely because it’s not solving a market problem.
The API overview usually appears on the homepage of the API. The homepage (the start of your docs) is a good place to put this overview because in this overview you also define your audience. Understanding your audience helps you orient the content in your API documentation appropriately.
Sample API overviews
Here are a few sample API overviews.
The Sendgrid overview starts with two key sections: “What is SendGrid?” and “Who is SendGrid for?” I like the straightforward approach. Even in the description of what SendGrid is, the authors don’t assume everyone knows what an SMTP provider is, so they link out to more information. Overall, in about 10 seconds you can get an idea of what the SendGrid API is all about.
Lyft’s API overview starts in a similar way, with sections titled “What is Lyft?” and “Why Use Lyft as a Developer.” Their homepage also provides information on access, rate limits and throttling, and testing. The Lyft authors also recognize that each tech domain has its own lingo, so they provide a glossary up front.
IBM Watson Assistant
IBM Watson Assistant starts off with a brief summary of the service, followed by a high-level diagram of the system and a summary about how to implement it. Including a diagram of your API gives users a good grounding about what to expect, such as the level of complexity and time it will take to incorporate the API.
Activity with API overviews
With the open-source project you identified, identify the API overview. Then answer the following questions:
- Does the documentation have an API overview?
- Does the overview clarify who the API is for?
- Does the overview indicate the market need or business problem the API solves?
- What questions do you still have about the API after reading the overview?
- How does the overview transition into a getting started tutorial or other first steps with the API?
62/120 pages complete. Only 58 more pages to go.
Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.