Mastering API Documentation
Summer 2025 Class Registerations are now open!
Welcome to "Mastering API Documentation," a comprehensive 7-week live virtual course tailored for developers, technical writers, and anyone eager to learn how to create effective API documentation. Throughout this structured journey, you'll acquire practical skills and insights to document APIs clearly and precisely, empowering you to communicate complex information with ease.
;Audience
This course is designed for technical communicators transitioning from UI to API writing and stakeholders needing to document or understand APIs. Relevant roles include technical writers, developers, product managers, and support specialists.
Course overview
This online course offers in-depth training on API documentation, blending theory and practical application. Key features include:
- Instructor-Led Classes: Gain insights into various aspects of APIs and documentation with live demonstrations, such as making API calls and documenting APIs.
- Hands-On Assignments: Complete assignments between classes to reinforce learning and apply new skills.
- Final Project: Create and submit an API documentation portal for peer review.
- Final Quiz: Test your understanding with a comprehensive quiz at the end of the course.
By the course's conclusion, participants will master API documentation principles, tools, and best practices. They will create clear, industry-standard documentation, collaborate effectively with developers.
Duration
This 7-part series runs weekly. Each session is approximately 90 minutes.
10.5 Hours of Classroom Learning with 8+ Hours of Offline Exercises!
Course Coverage & Topics
Class #1: Understanding APIs
This class introduces the fundamentals of APIs, covering their purpose, how they function, and how to interact with them using tools like Curl, web browsers, and JavaScript applications. It also explores API documentation, its key components, and the tools used to create and maintain it, with hands-on exercises in Swagger UI.
1. Course Introduction
- Welcome to the course
- About the instructor
- Course goals
- Course modules
2. API Requests with cURL
- Retrieve a random Chuck Norris joke in JSON format
- Retrieve a list of joke categories
- Retrieve a random Chuck Norris joke from a given category
3. API Requests in the Browser
- Retrieve a random Chuck Norris joke in JSON format
- Retrieve a list of joke categories
- Retrieve a joke by its ID
- Retrieve a random Chuck Norris joke from a given category (handling 404 errors)
4. Inspecting API Calls in Developer Tools
- "Get me a new one" button – observing request and response
- View API calls in Chrome DevTools (Free text search)
- Refresh page – observe new API call fetching fresh data
- Polling – API refreshes data every few seconds
5. API Documentation Overview
- Who is responsible for creating/maintaining API documentation?
- If a company hires me to do API documentation, what tools will I use and in what sequence?
- What are the key stages in the API documentation process?
- API documentation fundamentals
- API documentation types
- Sections in API documentation
- Challenges and opportunities
Offline Exercise: Hands-on API Documentation Exploration
- Explore Swagger UI to learn how to read API docs
Class #2: Structured Data & JSON
This class explores structured data with a focus on JSON, covering its format, objects, arrays, and nesting. It includes hands-on exercises with Swagger UI and Postman to construct and send JSON requests, interact with APIs, and handle authentication.
1. Introduction to JSON
- JSON as a data exchange format
- Structured Data
2. Exploring JSON Structures
- Tabular data
- JSON Objects
- JSON Arrays
- Nesting JSON Objects and Arrays
3. Working with Swagger UI
- Access Swagger UI
- Understanding the Interface
- Interactive Features
- Response Handling
- Demo: Swagger UI "Try-it-out"
- Codealong: Send a JSON payload
4. Exploring Postman
- Postman UI Walkthrough
- Understanding requests
- POST request example
- Sending request and code samples
- Codealong: Create request in Postman
Offline API Exercises (Swagger UI & Postman)
- These exercises refine API skills using Swagger UI and Postman, covering authentication, data structuring, and request formation.
Class #3: OpenAPI Deep Dive Part #1
This class provides a deep dive into OpenAPI and YAML, covering key components like the Info Object, servers, paths, operations, and responses. Through hands-on exercises in Swagger Editor and Curl, participants will practice structuring API definitions, troubleshooting errors, and making API requests.
1. Introduction to OpenAPI & YAML
- Introduction to OAS and YAML
- YAML basics: objects, arrays, nesting
2. Swagger Editor
- Swagger Editor, Understanding the Interface
- Common errors in Swagger Editor
3. Hands-on YAML Coding
- Add API version (key-value field)
- Info Object (object)
- Fix YAML errors based on messages
- Add a description to the Info section (first documentation task)
4. Defining API Structure
- Servers and paths
- Codealong: Add course API's servers section
- Operations
- Tags
- Codealong: Add course API's tags with tag and description
- Collection endpoints
- API responses
- Codealong: Investigate API responses
5. JSON Schema in OpenAPI
- JSON schema and OpenAPI
- Codealong: Send a request and analyze JSON schema violations
- Data types and keywords
6. Curl & API Requests
- Curl Crash Course
- Why is Curl important for API documentation?
- Curl command breakdown
- Codealong: Compose and send a "Get a List of" request
Offline Exercises with Curl
- Practice API requests with Curl, covering filtering, sorting, searching, pagination, authorization, and JSON formatting for various HTTP methods.
Class #4: OpenAPI Deep Dive Part #2
This session focuses on query parameters, authentication, and CRUD operations in OpenAPI and Curl. Participants will practice constructing API requests, handling security schemes, and documenting API interactions using Curl and Swagger UI.
1. Query Parameters
- Sort / Order
- Projection Filters
- Selection Filters
- Search (q)
- Pagination: Cursor vs. Page-based
- Codealong: Curl - passing query parameters
2. Authentication & Authorization
- Authentication and Authorization Overview
- Security Schemes
- Codealong: Curl - Add authorization header to a request
3. Resource Management
- Creating resources
- Get by ID and path params
- Updating a Resource
- Deleting a Resource
Offline Exercises
- Document how to use Course API endpoints and query parameters to chain requests and achieve a specific goal.
Class #5: API Flows and Diagramming Part #1
This session covers user journeys, API flows, and diagramming with Mermaid. Participants will map user interactions, translate them into API flows, and practice authentication flows in a React Admin Panel.
1. API Flows and Diagramming Overview
- User Journeys
- Overview of Course API and Apps
2. User Journey Diagrams
- The Patron Persona User Journey
- The Staff Persona User Journey
- The Admin Persona User Journey
3. Mermaid Diagrams
- Diagrams as Code - Flow Diagrams
- Mermaid UI Walkthrough
- Flow Diagrams
4. Translating User Journeys to API Flows
- Detour: Authentication and Authorization
- The Authentication API Flow
5. React Admin Panel Codealong
- Logging into the Admin Panel
- Open Google Chrome Developer Tools
- Logging into the React Admin Panel
- Token API Call
- View "Get a List of" API Call in Response
Offline Exercises
- Simulate API flows by navigating the Admin Panel, following user journeys, and executing key API interactions.
Class #6: API Flows and Diagramming Part #2
This session focuses on the sequence diagramming of API flows, including user login, admin login, and patron actions, using tools like Curl and Mermaid. Participants will diagram and analyze authentication and admin/patron API flows, then apply their learning with hands-on exercises using Postman.
1. Sequence Diagramming Basics
- Sequence Diagramming - basic, non-technical example
2. Authentication API Flow
- The Authentication API flow
- Account creation
- User login
- Refreshing the access token
- Sequence Diagramming the Authentication API Flow
3. Persona API Flows
- The Admin API Flow
- The Patron API flow
- The Staff API flow
- Sequence Diagramming Persona API Flows
Offline Exercises
- Create requests for Getting started, POS, KDS, and the Admin Panel
- Getting started tutorial using the Auth API Flow
- Document Use Cases: POS, KDS, Admin Dashboard
Class #7: Refining API reference and Markdown
This session focuses on refining API references, covering topics like the difference between formal and informal elements, documenting endpoints, fields, and status codes, and writing error messages. Participants will practice these concepts through hands-on exercises in the Swagger Editor, improving the ability to create clear and detailed API documentation.
1. Understanding API References
- What is API Reference?
- Formal vs. Informal OpenAPI Elements
- Writing Informal Descriptions
- Balancing Level of Detail
- Markdown in OpenAPI
2. Documenting API Endpoints
- Summarizing Endpoints
- Describing Endpoints
- Documenting Fields
- Describing Status Codes
- Writing Error Messages
Offline Exercises
- Document All API Resources in API Reference
Hands-on Assignments and Final Project
Reinforce learning with interactive code-alongs and offline exercises, documenting the Course API based on lessons. This hands-on approach builds practical API documentation skills.
By course end, you'll have a complete API documentation portal and guidance on publishing it as a portfolio piece.
Select a 2025 Summer Schedule
Each schedule is limited to 30 students, so reserve your spot while you can!
Class times are shown in Pacific Time (PT) below. Check your timezone here.
Schedule #1: 05 May to 23 June
| Class # | Date | Time | Duration (minutes) |
|---|---|---|---|
| 1 | 05 May 2025 | 8:00am - 9:30am PT | 90 |
| 2 | 12 May 2025 | 8:00am - 9:30am PT | 90 |
| 3 | 19 May 2025 | 8:00am - 9:30am PT | 90 |
| 4 | 02 June 2025 | 8:00am - 9:30am PT | 90 |
| 5 | 09 June 2025 | 8:00am - 9:30am PT | 90 |
| 6 | 16 June 2025 | 8:00am - 9:30am PT | 90 |
| 7 | 23 June 2025 | 8:00am - 9:30am PT | 90 |
Schedule #2: 07 July to 18 August
| Class # | Date | Time | Duration (minutes) |
|---|---|---|---|
| 1 | 07 July 2025 | 8:00am - 9:30am PT | 90 |
| 2 | 14 July 2025 | 8:00am - 9:30am PT | 90 |
| 3 | 21 July 2025 | 8:00am - 9:30am PT | 90 |
| 4 | 28 July 2025 | 8:00am - 9:30am PT | 90 |
| 5 | 04 August 2025 | 8:00am - 9:30am PT | 90 |
| 6 | 11 August 2025 | 8:00am - 9:30am PT | 90 |
| 7 | 18 August 2025 | 8:00am - 9:30am PT | 90 |
What to expect after buying the course
After you purchase the course, you'll receive an email with step-by-step instructions on joining the live classes on our webinar platform and accessing the course Discord community for ongoing support and discussions.
Videos
Postman
This video shows how you can use query parameters to filter the API response in Postman.
Swagger Editor
This video walks through the process of documenting an endpoint using Swagger Editor, showcasing best practices in action.
Swagger UI
This video explores how API reference descriptions provide insights into how end users interact with the API through a user interface, helping to clarify the connection between front-end actions and back-end processes.
Diagrams as Code: Mermaid
This video explores how to create sequence diagrams that map out the flow of API calls for a specific use case.
Questions?
Feel free to contact the instructor at mark.wentowski@docsgeek.io
Refund policy
"Mastering API Documentation" is a live, virtual course. Due to the nature of live instruction and limited spots, we do not issue refunds unless there are extraordinary circumstances. If you encounter extraordinary circumstances and cannot attend, you may request a refund by emailing your reason to mark.wentowski@docsgeek.io. If you are refunded, any applicable processing, platform, or program fees will be deducted from the refunded amount.