The workshop will cover 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
- 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
- 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.
Date and time
Sat, March 10, 2018
9:00 AM – 1:30 PM MST
Metropolitan State University of Denver: Room CN113
1198 11th Street
Denver, CO 80204
The cost ranges from $10-75 depending on whether you’re a member or student. You can sign up through Eventbrite.
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include the following technical communication topics: Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, and certificate programs. I'm interested in information design, API documentation, visual communication, information architecture and findability, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.