Following this course will take you from zero to … well slightly better
Crash Course in APIs for Technical Writers
Guide to APIs
API Docs
One of the most asked questions I see coming from technical writers is, “What is an API?” There are a lot of blogs on this topic, for example, Kesi Parker has written many articles on APIs, those can be found here and here. I find articles like these helpful to understand the concept behind learning something new, but nothing is better than trying it for yourself. The following article is my attempt to provide a clear road map for technical writers to follow in order to learn what API documentation is all about.
In this Crash Course, you will learn:
- What is an API
- Why APIs are important
- How to use an API
- How to write documentation for APIs
I am a firm believer in being a lifelong learner. After you finish reading this article, don’t stop learning. Consider joining a writing community to learn from others.
Getting Started
To get started learning about APIs, it would be useful to understand what an API is. Tom Johnson, a technical writer at Amazon, has a great guide on APIs: I’d Rather Be Writing. You don’t need to read through the whole thing, but it is definitely a great primer on APIs. Tom Johnson’s blog/course hybrid has been a staple in the technical writing community and is usually the first place people are sent to learn about API documentation.
Nordic APIs have a great read on what should be included in API documentation. Nordic API’s article lists 7 things API documentation can’t live without. I recommend reading through this article to understand the different aspects of API documentation. There are links throughout this article that could send you down a rabbit hole of APIs.
Mozilla’s API course for developers walks users through web APIs and how they will be run. I included this in the getting started because it has all the tools to take you to a competent user on APIs. If you don’t understand everything on the getting started page, that is okay. You should be able to go back to some of the resources and understand the tools they are referencing eventually.
How to Write an API
Spotlight
Spotlight is an API client, similar to Postman, that focuses on empowering your APIs. The blog section of their website offers great tips some highlighted articles are:
- Writing Documentation When You Aren’t A Technical Writer Part 1, Part 2 This series can help you understand what developers are looking for when they are reading documentation.
- Rest API Documentation Templates This article highlighted necessary items to include in REST API documentation.
I found Spotlight’s blogs easy to understand and fun to learn from. They give quite a bit of examples throughout their blogs.
Swagger
Swagger — Powered by SMARTBEAR, is one of the most widely used REST API tools for developers. Some of the articles I found helpful are:
- Best Practices in API Documentation This article provides a high level overview of what you should include in your API documentation as a whole.
- Learn How to Document an Existing API with Swagger Is a free e-book white-paper-level guide on documenting APIs with Swagger, although you can apply what you learn to any API documentations.
Examples
Imitation is the best form of flattery. I have included in this list some sites that showcase the best documentation for APIs. A lot of the documentation will include an easy getting started page that I recommend you try out.
Heroku is a great Hello World tutorial to get their API’s up and running. I would recommend choosing a language, such as Python, and going through their step-by-step lessons to get a better understanding. Heroku has a great platform and I don’t see it mentioned enough by technical writers.
Twilio has projects that will help you understand the nature of APIs and what can be accomplished with them. For example, their SMS project will walk you through how to send a SMS to your phone number through the command line.
Stripe is known for its 3 panel REST API documentation. Stripe is similar to Twilio in terms of walking the user through how-to. I found Stripe useful in the fact that it provides a lot of explanations around their examples. Twilio and Stripe’s documentation is referred to as the Gold Standard. So as you’re going through the examples, take note!
Perhaps not as well known, riak has a beautiful layout and gives a getting started tutorial which is easy to follow. This is one resource I wish I saw sooner. A lot of things clicked for me after I completed it.
Courses
I am a big believer in learning by doing, so I have gathered some courses that are useful in learning about APIs.
Cisco has multiple courses that will walk through different scenarios. I found that the Cisco course to be underutilized but it serves as a great starting point for many users. This is a beginners level course but has a lot of great information.
Postman is pretty much industry standard when it comes to calling APIs and it wouldn’t be complete if there wasn’t a way to document. Postman provides a Walk-Me inspired course on how to document an API. This is as close to a real world example as it gets and is fairly well done. A lot of developers use Postman to run and test APIs. Postman even allows you to set up an environment and test it online.
Books
Docs Like Code by Anne Gentle
The Chapter Specialty information: REST API docs gives an overview of how to use the Doc as Code approach to REST APIs. I found Gentle’s chapter useful in the fact that she describes how one might plan out documenting APIs.
Thank you for reading. If you would like to learn more about how to write documentation for APIs you can read my article here.
