REST APIs involve sending requests and receiving 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.

In this workshop 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 first learn about API documentation by using a simple weather API 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 more. Rather than learning about these concepts independent of any context, you learn them by immersing yourself in a real scenario using an API.

We’ll then transition into standards, tools, and specifications for REST APIs. You’ll learn about the most common sections in API documentation: resource descriptions, endpoints and methods, parameters, request examples, and response examples. We’ll also dive into specifications such as the OpenAPI specification and Swagger UI, which are commonly used for reference documentation. Exploring each of these sections will give you a solid understanding of how to document REST APIs.

You’ll also learn how to document the conceptual sections for an API, such as the getting started tutorial, status and error codes, authorization, sample apps and SDKs, code tutorials, and more. To gather insights here, you'll analyze examples of REST API documentation from various companies, inferring best practices and techniques.

Finally, we’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.

You can access the course materials online at https://idratherbewriting.com/learnapidoc. On this site you can preview the course slides and the activities to get a better sense of the material. This workshop is open to anyone but is intended usually for the following types of people:

• Professional technical writers looking to transition from GUI documentation into more API-focused documentation for developers.
• Students learning how to prepare themselves technically to succeed in the tech comm field, which is becoming more focused on developer documentation.
• Developers who are documenting their own APIs and want to know best practices for structure, terminology, and style with tech docs.

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 and JavaScript.

What You'll Need Prior to the Workshop

It helps to set up a few tools and other details prior to the workshop:

• 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 Chrome. 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. (Note: Choose one of the “free” versions to install curl.)
• Git. Git is a version control tool developers often use to collaborate on code. For Windows, see https://gitforwindows.org/ to set up Git and the Git BASH terminal emulator. For Mac, see Downloading Git and also consider installing iTerm2.
• GitHub account. GitHub will be used for various activities, sometimes to demonstrate the Git workflow and other times as an authentication service for developer tools. If you don’t already have a GitHub account, sign up for one.
• Stoplight account. Stoplight provides visual modeling tools for working with the OpenAPI specification. Create a Stoplight account using your GitHub credentials. (You don’t need the app.)
• OpenWeatherMap API key. We’ll be using the OpenWeatherMap API for some exercises. It takes a couple of hours for the OpenWeatherMap API key to become active, so it’s best if you get the API key ahead of time — then when you get to the OpenWeatherMap API activities, you’ll be all set. To get your (free) OpenWeatherMap API key, go to https://openweathermap.org/. Click Sign Up in the top nav bar and create an account. After you sign up, sign in and find your default API key from the developer dashboard. It’s under the API Keys tab. Copy the key into a place you can easily find it.

Workshop Location

The workshop will be held in Mountain View, California, at the Computer History Museum in the Boole room. This room holds 50. Directions are available here. After entering the museum, go up the stairs to find this workshop room.

FAQs

How do I know if the workshop will any good?

I've given this workshop multiple times and have refined the material and activities to improve it after each one. You can see some feedback from previous workshops here and here. On average from these last two workshops, about 57% of the participants rated it as Excellent and 40% rated it as Good.

What can I bring into the event?

Bring your computer and make sure you've set up the tools and other setup specified in "What You'll Need Prior to the Workshop" above.

How can I contact the organizer with any questions?

Yes, reach out to me, Tom Johnson, at tomjoht@gmail.com or online at https://idratherbewriting.com/learnapidoc/contact.html with any questions.

What's the refund policy?

Refunds are possible 7 days prior to the workshop. After that, refunds are not possible.

Is my registration fee or ticket transferrable?

Yes, you can transfer your registration/ticket to another person.

Is it ok if the name on my ticket or registration doesn't match the person who attends?

Yes, this is fine.

Will lunch be provided?

Yes, lunch will be provided at the event.