Mastering API Documentation

This 6-week bi-weekly course will equip you with essential skills to write industry-standard API documentation. Gain deep insights into REST APIs and API design, set up development environments and tooling for API testing, establish docs-as-code CI-CD pipelines, and use static site generators for API documentation portals. Learn to chart API flows, create step-by-step recipes, and write effective API references, along with get-started guides, code samples, and error handling techniques.

The registeration for the 2024 Fall-Winter course has closed. Click the link below to join the waitlist for the next schedule and you'll be notified when it is available:

;

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 Sessions: 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 sessions 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 6-part series runs biweekly. Each session is approximately 90 minutes.

What's Covered in This Course

Day #1: Foundations and setup

1. Prerequisites: Setting up
a dev environment

  • Download software
  • Create a GitHub account
  • Install Git Bash (Windows)
  • Configure SSH for GitHub
  • Clone the course repository
  • Install Node.js
  • Run the static site generator
  • Set up a CI-CD pipeline
  • Run the Docker containers
  • Access the Course Postman collections
  • Verify your set up

2. Course Introduction

  • API vs UI writing
  • API writing challenges
  • About the instructor
  • Course overview
  • About the Discord channel
  • Looking ahead tech writing and AI
  • The Point-of-Service (POS) Platform
  • Welcome to the course

3. Web API Basics

  • API business domains
  • API lifecycle roles
  • Internal vs External APIs
  • What is an API?

4. API Documentation
Fundamentals

  • API Documentation common issues
  • Developer portals vs API docs
  • How API writing relates to API testing
  • Sections in API documentation
  • Technical communicator challenges
  • The technical communicator's role
  • Types of API documentation
  • Why APIs need documentation

5. Exploring the dev environment

  • Tools and repos walkthrough
  • What is docs-as-code?
  • How to use the terminal
  • Authoring using text editors
  • Git commands and workflow

Day #2: Interacting with APIs

6. Introduction to OpenAPI

  • Comparing JSON to YAML
  • JSON request body exercise
  • JSON tutorial
  • Using Try-it-out
  • OpenAPI components
  • OpenAPI tooling
  • Swagger Editor
  • Swagger UI
  • What is OpenAPI?
  • The OpenAPI format

7. Postman UI Walkthrough

  • Introduction to Postman
  • Key features and capabilities
  • Exploring the Course API
  • Making a request
  • Generating curl Code from Postman

8. cURL Crash Course

  • What is cURL?
  • Importance for API Documentation
  • Making requests with cURL
  • Example usage with generated code

9. Fetching real data using an API

  • Introduction to web apps
  • Introduction to API fetching
  • JavaScript Fetch API
  • Making API calls in JavaScript
  • Handling API responses

Day #3: OpenAPI Deep Dive

10. High-level sections

  • Smallest possible OpenAPI spec
  • Servers and paths
  • Endpoints and operations
  • Tags

11. Responses

  • Collection endpoints
  • API responses
  • JSON schema
  • Example response body

12. Parameters

  • Data types and keywords
  • Query parameters
  • Sorting results
  • Filtering results
  • Paginating resources

13. Resources

  • Creating resources - POST
  • Get by ID and path params
  • Update a resource - PUT
  • Delete a resource - DEL
  • Subresources
  • Action resources

14. Authentication

  • Authentication methods
  • Security schemes

Day #4: API design and user flows

15. Collecting source material

  • API development approaches
  • Cardinality
  • Course API introduction
  • Database modeling
  • Diagramming using code
  • Domain models to API resources
  • Domain modeling
  • ER diagrams
  • Functional requirements
  • Understanding API development
  • User stories

16. Charting API flows

  • Overview
  • React Admin portal setup
  • Course API authentication
  • The admin API flow
  • The admin user journey
  • The authentication API flow
  • The patron API flow
  • The patron user journey
  • The staff API flow
  • The staff user journey
  • User journeys to API flows
  • User journeys

17. Planning your documentation

  • Determining topic types
  • Choosing tools and formats
  • Defining a feedback process
  • Defining documentation goals
  • Determining topic types
  • Establish a topic hierarchy
  • Understanding developer behaviors
  • Visual elements

Day #5: API reference, concepts and onboarding

18. Generating API reference

  • Documenting fields
  • Markdown in OpenAPI
  • Summarizing endpoints
  • Documenting endpoint descriptions
  • Documenting error handling
  • Documenting fields
  • Documenting responses
  • Formal vs informal descriptions
  • Identifying anti-patterns
  • Markdown in OpenAPI
  • Summarizing endpoints
  • Writing informal descriptions

19. Exploring conceptual topics

  • Authentication and authorization
  • API introduction and use cases
  • Additional topics
  • Authentication and authorization
  • C4 diagramming the POS platform
  • Diagramming the API flows
  • High-level software architecture
  • Key concepts and terminology
  • Resource object descriptions

20. Showing how to get started

  • The authentication flow
  • About API requests section
  • Building Postman authentication requests
  • Create a session
  • Direct the reader towards next steps
  • Making a request section
  • Sequencing authentication
  • The authentication flow
  • Using the response section
  • Visualize the getting started process

Day #6: Error handling, code samples, and recipes

21. Detailing error handling scenarios

  • API responses recap
  • Failure status codes
  • OAS errors vs problem schema
  • Outlining the troubleshooting guide
  • Overview
  • Sequencing error handling scenarios
  • Uncover the range of possible errors

22. Illustrating with code samples

  • Adding code samples
  • Example functionality template
  • Identify functionalities
  • Mapping functionalities to API calls
  • The course API’s query components
  • What is an API functionality

23. Crafting step-by-step recipes

  • Adding code samples
  • Break down the recipe into steps
  • Diagram the recipe flow
  • Example recipe template
  • Identify recipes
  • Mapping recipe steps to API calls
  • What is a recipe?

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.