I'm giving an API Documentation Workshop in Mountain View, California, on August 30, 2019. Although I've given more than a dozen API documentation workshops at various conferences over the past several years, this one is different. For this workshop, I'm organizing it myself. You can register on Eventbrite.
Previous API workshops I’ve given have usually been by request through some organizing sponsor, such as STC group, private company, or conference. But I’ve come to wonder if that organizing group is even necessary, so I’ll just experiment at least once giving the workshop on my own, marketing it myself, setting up the venue myself, handling registration myself, etc. If it’s successful, I’ll repeat it regularly. And if it’s not, I’ll at least have more experience running an event.
Here are the details:
Title: API Documentation Workshop Instructor: Tom Johnson Date: August 30, 2019 Venue:Computer History Museum Location: Mountain View, California Time: 9am to 5pm Cost: $399 before Aug 1, $499 after Aug 1
Here’s a description of the API documentation workshop:
API Documentation Workshop
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.
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 specificationand 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.