In this course on writing documentation for REST APIs, instead of just talking about abstract concepts, I contextualize REST APIs with a direct, hands-on approach.
You’ll learn about API documentation in the context of using some simple weather APIs to put a weather forecast on your site.
The idea is that rather than learning about these concepts independent of any context, you learn them by immersing yourself in a real scenario while using an API. This makes these tools and technologies more meaningful.
In a nutshell, REST APIs (which are a type of web API) involve requests and responses, not too unlike visiting a web page. You make a request to a resource stored on a server, and the server responds with the requested information. The protocol used to transport the data is HTTP. “REST” stands for representational state transfer.
I dive more into the principles of REST in What is a REST API? In your REST API documentation, you describe the various endpoints available, their methods, parameters, and other details, and you also document sample responses from the endpoints.
In this course, after you practice using an API like a developer, you’ll then shift perspectives and “become a technical writer” tasked with documenting a new endpoint that has been added to an API.
As a technical writer, you’ll tackle each element of a reference topic in REST API documentation:
Diving into these sections will give you a solid understanding of how to document REST APIs. You’ll also learn how to document the non-reference sections for an API, such as the getting started and request authorization sections.
Finally, you’ll dive into different ways to publish REST API documentation, exploring tools and specifications such as GitHub, Jekyll, and other Docs-as-code approaches. You’ll learn how to leverage templates, build interactive API consoles so users can try out requests and see responses, and learn how to manage your content through version control.
I also dive into specifications such as the OpenAPI specification and Swagger, which provides tooling for the OpenAPI specification. Additionally, I included a section on documenting native library APIs and generating Javadoc. Throughout it all, I put these tools in a real, applicable context with examples and demos.
This course is organized into the following sections:
You don’t have to read the sections in order — feel free to skip around as you prefer. But some of the earlier sections (such as the section on Using a REST API like a developer, and the section on documenting endpoints) follow a somewhat sequential order with the same weather API scenario.
Because the purpose of the course is to help you learn, there are many activities that require hands-on coding and other exercises. Along with the learning activities, there are also conceptual deep dives, but the focus is always on learning by doing. Where there are hands-on activities, I include an activity graphic like this:
I refer to the content here as a “course” instead of a book or a website, primarily because I include a lot of exercises throughout in each section, and I find that people who want to learn API documentation prefer a more hands-on “course” experience. However, this content is just as much a book or website as it is a course.
If you do have some familiarity with programming concepts, you might speed through some of the sections and jump ahead to the topics you want to learn more about. This course assumes you’re a beginner, though.
Here are a few things you’ll need to do the exercises in this course:
If you’d prefer a short version of the course in video form, here’s a 1-hour video that covers the first three sections. I gave this presentation to the STC Silicon Valley chapter:
For a longer video, here’s a recording from a 4-hour workshop I gave to the STC Sacramento chapter:
If you’re following this course, you most likely want to learn more about APIs. I publish regular articles that talk about APIs and strategies for documenting them. You can stay updated about these posts by subscribing to my free newsletter at https://tinyletter.com/tomjoht.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson