If I were to look at your API documentation, what would I see? Would I see content focused only around the POSTs, GETs, PUTs, PATCHes, and DELETEs? Or, would I see comprehensive and clear documentation that solves my problems?
Let’s look at why clear documentation is important and how we can improve API adoption by answering the questions your API consumers are already asking.
API Documentation: A cry for help
Whether you are designing APIs for use by internal developers or public developers, clear API documentation is critical. Clear API documentation increases adoption and reuse, while decreasing the amount of code that other developers have to write to solve the same kinds of problems.
Some API docs are a cry for help. They lack the clarity and understanding necessary for a developers to use them. Sometimes it can be so bad that developers will just give up and find another API.
The worst offenders I have seen are API reference docs that look like this (using the OpenAPI Specification):
path: /organizations
get:
summary: Get all organizations
So, how do we make this documentation better? We need to start asking (and answering) some questions.
Question #1: How does your API solve my problems?
This documentation doesn’t solve my problem. It doesn’t inform. It doesn’t address the kinds of problems your API is designed to solve. It simply exposes resources to developers without any context.
Ensure that your API documentation has an introduction that covers what the API solves, what it doesn’t solve, and some example use cases that it has solved in the past. This will help establish a context for the reader, who may be trying to decide if your API is the right fit for their need.
Question #2: In what context do your APIs work?
Revisiting our example above, developers will read “Get all organizations” in your documentation and start asking the following:
- Are the organizations all of the currently registered orgs in the app?
- Or, are these the organizations that I am allowed to see?
- Or, are these the organizations that to which I currently belong?
- Do you send all of the results at once, or are they paginated?
- If the results are paginated, how can I control the page size and request additional pages?
Note the additional details that we need to add to our documentation to clarify what it does. It takes more than “Get all organizations” in our endpoint descriptions to help a developer understand and use your API.
Question #3: How do I get started using your API?
While many modern web APIs offer self-service onboarding, not every API does. If your API does offer self-service onboarding, call this out in your documentation as a benefit to getting started faster. For those that require time to go through a partnership program, include this in your documentation as well. This will ensure that the appropriate lead time is factored in prior to developers beginning the first ‘hello world’ integration.
Why include this inforrmation in your API documentation? Because not all developers start from the homepage of your developer portal. If your docs are available for indexing, they may stumble upon a direct link to your docs from a search engine. Be sure to include these details (or a link at minimum) to your onboarding process somewhere near the top of your API documentation.
Finally, don’t assume that all developers can “figure out” how to use your API. Every developer is at a different stage in their career. Some may have the same, more, or less experience than you do using web APIs. Take the time to explain, step-by-step, how to get started.
Engage in conversations with your API consumers
To write better documentation, we need to ask the same questions are API consumers are asking. To discover the questions your API consumers are asking and improve your documentation, it is best to engage in conversations with developers.
Engaging in discussions with your API consumers will lead to those critical ‘aha!’ moments that API providers need to improve their documentation. When this isn’t possible, try to find other developers to review your documentation and perhaps write some code to call your API (or pseudocode if you are still designing it).
Incorporating the answers into your documentation
Once we have identified the questions our documentation creates, we can then improve our API documentation to benefit current and future developers. Below is the updated documentation for our example endpoint that incorporates everything we discussed earlier (again, using the OpenAPI Specification):
path: /organizations
get:
summary: List all registered organizations
description: "Returns a paginated list of organizations registered within the application. Defaults to 20 per page, but pagination may be customized (see the request parameter details below).
Example that fetches 100 results for page 1:
```
GET /organizations?page=1&perPage=100
```
"
parameters:
- name: "page"
in: "query"
description: "The page number being requested. Defaults to 1"
required: false
type: "integer"
format: "int64"
default: 1
- name: "perPage"
in: "query"
description: "The number of results to return per page. Defaults to 20, maximum is 200 results per page"
required: false
type: "integer"
format: "int64"
default: 20
maximum: 200
That’s better. We now provide some clarity by defining the feature that the endpoint provides. We can then expand the details of what it does through the description, allowing us to expand on the details of the endpoint, query params, response payload format, etc.
Putting it all together
Our documentation should answer the questions our API consumers have when they first encounter your API. Take the time to understand the kinds of questions your API consumers have when using your API and feed these insights back into your API documentation. This will result in greater understanding by our API consumers of what our API has to offer, the context of when to use it, and how your API will help them build software that solves the problems at hand.
We heard your cry for help, and so the Tyk team has recently made all Tyk documentation Open Source for your viewing, editing and ‘critiquing-until-it’s-borderline-ripped-to-shreds’ pleasure. Please – be our guest.
Interested in our process to open source Tyk documentation? Visit Tyk Docs.
