Search results

Documenting APIs: A guide for technical writers

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

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.

As you use the API, you’ll learn about endpoints, parameters, data types, authentication, curl, JSON, the command line, Chrome’s Developer Console, JavaScript, and other standards, tools, and technologies associated with REST APIs.

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.

Response and request model for REST APIs
REST APIs involve requests and responses over HTTP protocol

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.

From practice to documentation

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:

  1. Resource descriptions
  2. Endpoints and methods
  3. Parameters
  4. Request example
  5. Response example

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, status and error codes, request authorization, and more.

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 cover how to document native library APIs and generate Javadoc. Throughout it all, I put these tools in a real, applicable context with examples and demos.

Course organization

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:


Other topics consist entirely of activities. The course has the following activities:

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.

Will this course help you get a job in API documentation?

The most common reason people take this course is to transition to an API documentation. This course will help you make that transition, but you can’t just passively read through the content. You need to do the activities outlined in each section, especially those topics that involve working with content from an open-source project. These activities are key to building experience and credibility with a portfolio.

No programming skills required

As for the needed technical background for the course, you don’t need any programming background or other prerequisites, but it will help to know some basic HTML, CSS, and JavaScript.

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.

Some of the code samples in this course use JavaScript. JavaScript may or may not be a language that you actually use when you document REST APIs, but most likely there will be some programming language or platform that becomes important to know.

JavaScript is one of the most useful and easy languages to become familiar with, so it works well in code samples for this introduction to REST API documentation. JavaScript allows you to test out code by merely opening it in your browser (rather than compiling it in an IDE). (I have a quick crash-course in JavaScript here if you need it.)

What you’ll need

Here are a few things you’ll need to do the exercises in this course:

  • Text editor. (Atom editor or Sublime Text are good options, and they work on both Mac and Windows.)
  • Chrome browser. Chrome provides a Javascript Console that works well for inspecting JSON, so we’ll be using this browser. Firefox works well too if you prefer that.
  • Postman. Postman is an app that allows you to make requests and see responses through a GUI client.
  • curl. curl is essential for making requests to endpoints from the command line. Mac computers already have curl installed. Windows users should follow the instructions for installing curl here.
  • Git. Git is a version control tool developers often use to collaborate on code. See Set Up Git for more details.
  • GitHub account. GitHub will be used for various activities and is commonly used as an authentication service for developer tools. If you don’t already have a GitHub account, sign up for one.
  • Stoplight App. Stoplight provides visual modeling tools for working with the OpenAPI specification. Create a Stoplight account using your GitHub credentials.

Video recordings

For video recordings of this course, see the Recorded Video Presentations. The most recent full-length video of the entire course is a half-day API workshop I gave in Denver.


I have various slides that cover different sections of this course. See the following:

These slides are all hosted on GitHub at I use RevealJS for slides, which lets me create the slide content in HTML. If you’re a teacher using material from this course in your classroom, you can adapt the slides as needed for your lessons.

Stay updated

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.

3% Complete

3/108 pages complete. Only 105 more pages to go...


Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.