In this book 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 more meaningful.
After you use the API as 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.
Finally, you’ll dive into different ways to publish REST API documentation, exploring tools and specifications such as API Blueprint, Swagger, RAML, readme.io, Jekyll, and more.
You’ll learn how to leverage templates, build interactive API consoles so users can try out requests and see responses, and learn different ways to host and publish your documentation.
Organizationally, this book is divided into the following sections:
You don’t have to read the chapters in order — skip around as you prefer. But some of the earlier sections on using a REST API like a developer and 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.
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 book assumes you’re a beginner, though.
Here are a few things you’ll need to do the exercises in this book:
If you’d prefer a short version of the course in video form, see this workshop I gave to the STC Sacramento chapter:
If you’re reading this book, 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.
If you would like to contribute back and encourage more available content and resources, you can click the Donate button below and contribute any amount.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson