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.

You can access the course materials online at https://idratherbewriting.com/learnapidoc/workshop.html to get a better sense of the material we'll cover and the agenda. 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

Flexible Meeting Space #3
655 Montgomery Street Suite 400
San Francisco, CA 94111

Directions on Google Maps are available here.

Workshop Time and Agenda

The workshop is from 9am to 5pm. The high-level agenda is as follows:

8am - 9am: checkin, breakfast
9am - 12:30pm: instruction + activities
12:30pm - 1:30pm: lunch
1:30pm - 4:30pm: instruction + activities
4:30pm - 5:00pm: individual consultations

You can see a more specific agenda here.

Parking

If you're driving, there's a parking garage in the building. You can also park at a nearby garage. If you're not driving, consider taking a Lyft or Uber. For example, from the Caltrain, take a Lyft over to the location.

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 okay 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?

Yes, we will wrap up at 4:30pm and then switch into 1:1 mode. At that time, I'll list all the names of people who want individual consulting, and we'll proceed through the list one by one. The venue closes doors at 5:30pm.

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

The workshop size is limited to 25 people. The room holds 30 people.