Skip to main content
Call for Reservations: 800-972-3165
API Documentation Workshop
9:00 AM - 11:59 PM Computer History Museum
Date: August 30, 2019 to August 30, 2019
Where: Computer History Museum, 1401 N Shoreline Blvd, Mountain View, California, United States, 94043
Phone: N/A
Event Type: Family
Ticket Price: N/A
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. 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. Rather than learning about these concepts independent of any context, you learn them by immersing yourself in a real scenario using an API.  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 specification and 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 respon