Search results

Recording of API documentation workshop in Denver

by Tom Johnson on Mar 12, 2018
categories: api-doc • podcasts • api-doc-site-updates

I recently gave a half-day API workshop in Denver on March 10, 2018. Topics in the workshop included how to document reference API content (endpoints, parameters, requests, etc.), what non-reference topics (for example, status and error codes, rate limiting, getting started, sample apps) are common, how to create an OpenAPI specification document and Swagger UI output, and more. You can view a recording of the workshop, browse the slides, and listen to the audio here. Because of the length, the content is divided into three parts.

Workshop activities

The activities we followed in the workshop are listed on the Workshop activities page in my API documentation course.

Video recordings

The recording of the workshop is divided into three parts. Each of these sections includes a video recording, audio file, and slides.

Part I:

Part II:

Part III:

Audio only recordings

Part I:

Download MP3

Part II:

Download MP3

Part III:

Download MP3

If you’re driving across the country and you want to listen to all audio combined into one consolidated file (consisting of parts I, II, and III), you can do so here:

Listen here:

Slides

If you just want to browse the slides, you can do so here:

Part I:

Part II:

Part III:

The slides are all stored on GitHub:

Event description

The workshop covered many of the topics from my API doc course. Here’s the workshop description.

API Documentation Workshop

REST APIs involve submitting 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. HTTP is the medium for transporting the information. “REST” stands for representational state transfer.

In this workshop on documenting REST APIs, you’ll learn about API documentation in the context of using a simple weather API to put a weather forecast on your site. As you use the API, you’ll learn about curl, Postman, Chrome’s Developer Console, JSON, and other details associated with REST APIs.

After making requests to an API, we’ll dive into each element of a reference topic in REST API documentation:

  • Resource descriptions
  • Endpoints and methods
  • Parameters
  • Request example
  • Response example and schema

We’ll also explore how the OpenAPI specification (formerly called Swagger) can provide a standard for describing an API. The OpenAPI defines specific properties in a particular order and hierarchy covering each aspect of reference documentation, from endpoints to requests to security and responses. After you have a valid specification document, you can feed it into specific frameworks and platforms (such as Swagger UI, SwaggerHub, or Spectacle) to automatically generate interactive documentation.

We’ll also dive into the non-reference sections in API documentation. These topics might include the following:

  • Getting started tutorial
  • Authentication
  • Status and error codes
  • How-to code tutorials
  • Sample apps and client SDKs

Finally, we’ll explore different ways to publish REST API documentation, looking at tools such as GitHub, Jekyll, and other docs-as-code approaches. You’ll learn how to choose the right source format, manage your content through version control, build from the server with continuous delivery, and more.

This workshop covers a broad range of topics, so the depth we go into with each area can vary based on the participants’ questions and interests. My approach is to first learn what questions and information needs participants have and then give emphasis to those areas. Questions and discussion throughout will be welcome. We will do some hands-on activities during the workshop, but we won’t get too detailed with technical activities, sticking more with high-level concepts and techniques.

Note that I didn’t talk much about docs-as-code publishing tools, as I covered this in a separate presentation on Docs-as-code tools and workflows.

The event was sponsored by the Rocky Mountain STC chapter and Write the Docs Denver. You can learn more about the event here: API Documentation Workshop.

Event details

Date and time

Sat, March 10, 2018
9:00 AM – 1:30 PM MST

Location

Metropolitan State University of Denver: Room CN113
1198 11th Street
Denver, CO 80204

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.

© 2024 Tom Johnson