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.
What's Covered in This Course
Class #1: Understanding APIs
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
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
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
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
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
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
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
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 purchasing the course, you'll receive an email with instructions to join the live classes on our webinar platform.
Before the course starts, you'll get an email with prerequisites, software setup, repo cloning instructions, and a Discord link.
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.