Up until this point, we’ve been focusing on the endpoint (or reference) documentation aspect of user guides. The endpoint documentation is only one part (albeit a significant one) in API documentation. You also need to create a user guide and tutorials.
Whereas the endpoint documentation explains how to use each of the endpoints, you also need to explain how to use the API overall. There are other sections common to API documentation that you must also include. (These other sections are absent from the Mashape Weather API because it’s such a simple API.)
In Mulesoft’s API tooling, you can see some other sections common to API documentation:
Although this is the Yahoo Weather API page, all APIs using the Mulesoft platform have this same template.
Some of these other sections to include in your documentation include the following:
Since the content of these sections varies a lot based on your API, it’s not practical to explore each of these sections using the same API like we did with the API endpoint reference documentation. But I’ll briefly touch upon some of these sections.
Sendgrid’s documentation has a good example of these other user-guide sections essential to API documentation. It does a good job showing how API documentation is more than just a collection of endpoints.
Beyond the sections outlined above, you should include the usual stuff that you put in user guides. By the usual stuff, I mean you list out the common tasks you expect your users to do. What are their real business scenarios for which they’ll use your API?
Sure, there are innumerable ways that users can put together different endpoints for a variety of outcomes. And the permutations of parameters and responses also provide endless combinations. But no doubt there are some core tasks that most developers will use your API to do. For example, with the Twitter API, most people want to do the following:
Provide how-to’s for these tasks just like you would with any user guide. Seeing the tasks users can do with an API may be a little less familiar because you don’t have a GUI to click through. But the basic concept is the same — ask what will users want to do with this product, what can they do, and how do they do it.
Perhaps no other genre of technical documentation has such variety in the outputs as API documentation. Almost every API documentation site looks unique. REST APIs are as diverse as different sites on the web, each with their own branding, navigation, terminology, and style.
Despite the wide variety of APIs, there is some commonality among them. The common ground is primarily in the endpoint documentation. But user guides have common themes as well.
In a blog post by the writers at Parse, they break down API doc content into three main types:
Reference: This is the listing of all the functionality in excruciating detail. This includes all datatype and function specs. Your advanced developers will leave this open in a tab all day long.
Guides: This is somewhere between the reference and tutorials. It should be like your reference with prose that explains how to use your API.
Tutorials: These teach your users specific things that they can do with your API, and are usually tightly focused on just a few pieces of functionality. Bonus points if you include working sample code.
This division of content represents the API documentation genre well and serves as a good guide as you develop strategies for publishing API documentation.
In Mulesoft’s API platform, you can see many of these sections in their standard template for API documentation:
I won’t get into too much detail about each of these sections. In previous sections of this course, I explored the content development aspect of API documentation in depth. Here I’ll just list the salient points.
In most API guide articles, you’ll find the following recurring themes in the guides section:
Guide articles aren’t auto-generated, and they vary a lot from product to product. When technical writers are involved in API documentation, they’re almost always in charge of this content.
The second genre of content is tutorial articles. Whether it’s called Getting Started, Hello World Tutorial, First Steps, or something else, the point of the tutorial articles is to guide a new developer into creating something simple and immediate with the API.
By showing the developer how to create something from beginning to end, you provide an overall picture of the workflow and necessary steps to getting output with the API. Once a developer can pass the authorization keys correctly, construct a request, and get a response, he or she can start using practically any endpoint in the API.
Here’s a list of tutorials from Parse:
Some tutorials can even serve as reference implementations, showing full-scale code that shows how to implement something in a detailed way. This kind of code is highly appealing to developers because it usually helps clarify all the coding details.
Finally, reference documentation is probably the most characteristic part of API documentation. Reference documentation is highly structured and templatized. Reference documentation follows common patterns when it comes to describing endpoints.
In most endpoint documentation, you’ll see the following sections:
If engineers write anything, it’s usually the endpoint reference material.
Note that the endpoint documentation is never meant to be a starting point. The information is meant to be browsed, and a new developer will need some background information about authorization keys and more to use the endpoints.
Here’s a sample page showing endpoints from Instagram’s API:
35/94 pages complete. Only 59 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson