From code reviews to the importance of design, developers disagree on a lot. But what most developers have in common is how quickly they’ll give up on even the best API if its documentation fails to answer questions like “what,” ”how,” and “why.”
Ensure your documentation at least touches on these key questions by providing:
- Robust API reference
- Language-specific examples
- Getting started guides
Each of these three sections, discussed in detail in this post, include three items that make up the nine “checkboxes” of our API documentation checklist.
Your reference provides the answers to what your API does, while language-specific examples show how you do it. Then, getting started guides and other tutorials fill in why the API is used in the way you’ve described.
Download the checklist above to share with your team and read on to see each covered in the sections below.
Robust API Reference
When you think of the best API documentation, it could be the API reference that comes to mind. This extensive page (and they’re often a single page) provides a place to see all functionality in one place. Within the checklist, there are three items to consider:
A single page of endpoints, grouped by functionality
No matter how good your search functions, developers often want to “Ctrl-F” to find what they’re after. A single page allows for this.
However, that does not keep you logically breaking up the reference. You should organize around resources or functionality. For example, a series of calls to add, remove, and update users should be grouped together.
Show example requests, including what it looks like to add data
Whoever said a picture is worth 1,000 words was not a developer. Examples are the images of API references. It’s one thing to say “POST data with a JSON object containing these fields.” It’s another to show it:
Make sure your requests have examples.
Provide models, but also show example responses
Perhaps more important than request data is response data. It may feel redundant to show similar responses for different endpoints (rather than from a single location), but a developer may only be looking at one endpoint. They should find what they need in one place. However the trend to display data models (likely driven by the OpenAPI standard) is useful.
Notice both the example response, but also the “Schema” option to see the model view of the response data. This transparency into what to expect can help developers build structures in their code to inspect responses and build requests.
Language-specific examples
Developers integrate with APIs in the language their organization uses—or whichever they’re most comfortable. Documentation that uses language-specific examples makes it easier to take the next step. Within the checklist, this breaks down to three more items:
HTTP examples with curl
Don’t just show the endpoints in your API reference. Provide copy-paste samples with the curl command, so developers can see your API in action in their own terminal. You can get fancier with HTTPie examples or Postman collections, but make sure you check off this basic example first.
SDKs and example calls with each
Give developers a couple programming language options with client libraries. Make sure to meet the popular languages of your community, which often will include Node, Python, Ruby, Java, or PHP. Translate each curl command into a call from the SDK, using a selector to “set” their preferred language.
APIMatic (whom I advise) provides this functionality in its developer experience portal.
Sample code and starter apps
It’s one thing to show individual calls, but you API docs can expand the scope slightly for an even better experience. Create contained sample apps for Hello World and other common use cases. You can put them in easily-cloneable GitHub repos, but be sure to include them prominently in your documentation.
Since entire apps take more effort than sample calls, you can start small. Pick your most popular language or two and create a minimal example. When you give a developer somewhere to start, they may be more likely to integrate more completely.
Guides and Tutorials
With the “what” and “how” of API documentation checklist covered, now it’s time to communicate why the API is used. You need to give developers real-world context to help them see where your API fits in. For that to success, go beyond the reference and code samples to uncover your API’s use cases.
In the checklist, this breaks down to three final items:
Getting started guide
Pick a single, simple “hello world” use case. You’ll want to give developers a quick win they can build upon. Your tutorial should walk them through the basics of getting started—and reiterate benefits of using your API.
Beware multiple “getting started” guides, because it won’t be clear which to use. You can create a guide for each programming language you support, but make sure it’s clear they’re not separate tutorials. A series of language links on the documentation home page or from a single getting started page can help here.
Tutorials for common use cases
Your API is likely more complex than the quick win in the getting started guide. Build your other tutorials around common ways your API is used. It’s important to “seed” a developer’s imagination with possible applications of your API, even if one aim of the API is to generate new ideas. These initial concepts help ground your API in the real world.
Frame these additional tutorials around real problems and solutions. Make sure they’re not oriented toward specific features without explaining the benefits of the feature.
Sample apps to kickstart building
You can make your guides and tutorials even more useful with complete sample apps. Include the code needed to get started with a use case. These examples can be stored in GitHub repositories or similar locations that make them easy to copy. Just make sure they also have a location on your developer site.
You’ll want to pair each sample app with a tutorial or other walkthrough. Remember that code alone does not provide the context needed, nor help developers through potential trip-uips.
Start Checking the Boxes
Look for the nine items in this API documentation checklist on your site, then work toward including the ones you’re missing. For reference, you can download a PDF of this checklist or use the list below.
- A single page of endpoints, grouped by functionality
- Show example requests, including what it looks like to add data
- Provide models, but also show example responses
- HTTP examples with curl
- SDKs and example calls with each
- Sample code and starter apps
- Getting started guide
- Tutorials for common use cases
- Sample apps to kickstart building
Once complete, you’re well on your way to a great developer experience for your API.