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, you'll learn about 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.

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 dive into specifications such as the OpenAPI specification and Swagger UI, which are commonly used for API 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.

This workshop is open to anyone but is intended usually for the following types of people:

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

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:

• Laptop with power cord. Make sure you bring your computer, as we'll be doing various activities. Power strips will be available to plug in.
• Text editor. Install Sublime Text (unless you have some other preferred text editor such as Atom, Visual Studio Code, etc.)
  
• 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. Also, in order to read JSON responses more easily in the browser, install the JSON Formatter Chrome extension.
• Postman. Postman is an app that allows you to make requests. Note: Downlod the Postman app rather than using a browser extension or site.
• curl. curl is essential for making requests to endpoints from the command line. Macs and Windows 10 computers already have curl installed by default. (Windows users with older versions should follow the instructions for installing curl here.)
• 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.
  
• 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.
• 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, your key is emailed to you. You can also find your default API key from the developer dashboard. under the API Keys tab.

About the Instructor

Tom Johnson is a technical writer, blogger, and podcaster based in Santa Clara, California. In addition to his blog, https://idratherbewriting.com, he has developed an extensive online course on Documenting REST APIs at https://idratherbewriting.com/learnapidoc. Over the last decade, he has given more than 100 presentations at various events and he has taught more than a dozen API documentation workshops.

Workshop Location

9100 S Sepulveda Blvd Ste 208
Los Angeles, CA, 90045

(This location is close to LAX airport.)

Workshop Time and Agenda

The workshop is from 9am to 5pm, with a one hour break for lunch.

FAQs

What should I bring to the workshop?

Bring your laptop 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?

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. All refunds are charged a nonrefundable $25 Eventbrite processing fee.

Is my registration fee or ticket transferrable?

Yes, you can transfer your registration/ticket to another person. (It's fine if the name on your ticket does not match the registration name.)

Will lunch and other food be provided?

Yes, lunch will be provided at the event, with vegetarian options available. Additionally, a light breakfast and an afternoon snack (with coffee) will also be provided.

Are discounts available if I buy multiple workshop tickets, such as registering multiple people from the same company?

If you're purchasing multiple workshop registrations, you can receive for a 10% discount on the ticket price. Email me (tomjoht@gmail.com) for the promo code to enter during checkout.

Will this event be recorded?

I am not planning to record this workshop.

Can the workshop be streamed for remote participants?

No, the workshop won't be streamed.

I need specific advice about a particular aspect of API documentation I'm working on. Will you provide some 1:1 consulting time?

There will be time for individual consultations during the workshop.

Is there a limit to the number of participants in the workshop?

The workshop size is limited to 25 people.

Reviews from previous participants

Here's some feedback from previous participants of the workshop:

"Workshop was excellent and comprehensive. We covered a variety of topics that someone new to the field or a technical writing role would find essential, including understanding the basics of how APIs work, making http requests, the structure of good API documentation, technical concepts, and even a section on career advice. Software technical writing can often be a solitary adventure and it's hard to find good resources and best practices. This workshop provided both."

"This workshop gave me what I needed in order to feel confident about finding work as an API tech writer. It was great! Definitely recommend it for those who want to learn more about API documentation."

"This workshop is extremely helpful in figuring out where you are in your quest to become an -- or become a better -- API technical writer. Tom provides a great overview of the entire process, while explaining some of more esoteric topics in more detail. The workshop was very helpful as I try to transition from being a traditional technical writer to a much more "technical" technical writer."

"Your review and comments on existing API docs out there were very helpful. It helped me better analyze what to look for in good API documentation. The discussion about the different approaches was very interesting. I hope to use the information from this workshop and the course to help my Developers to get started with the new API development phase. Thank you!!"