Blog
API documentation course
Course home
I: Introduction to REST APIs
II: Using an API like a developer
III: Documenting API endpoints
IV: OpenAPI spec and generated reference docs
V: Step-by-step OpenAPI code tutorial
VI: Testing API docs
VII: Conceptual topics in API docs
VIII: Code tutorials
IX: The writing process
X: Publishing API docs
XI: Thriving in the API doc space
XII: Native library APIs
XIII: Processes and methodology
XIV: Metrics and measurement
XV: Additional resources
Download PDFs
About
About me
Contact
Presentations
Newsletter
Site analytics
Advertising
Archives
2023
2022
2021
2020
2019
2018
2017
2016
2015
2014
2013
2012
2011
2010
2009
2008
2007
2006
Posts by tag
Series
Trends to follow or forget
Sitting, standing, and walking
Journey away from smartphones
A hypothesis about influence on the web and the workplace
Mobility
Reflecting seven years later about why we were laid off
Simplifying complexity
Value arguments for docs and tech comm
Visual communication
Basketball
Biking
Testing documentation
Voiceover techniques
Seven deadly sins of blogging
API documentation survey
Author in DITA and Publish with WordPress
DITA journey
Dallas STC Summit videocasts
Get a Job in Technical Writing
Innovation in tech comm
Jekyll versus DITA
Quick reference guides
Search engine optimization
User-centered documentation
User-centered documentation principles
My journey to and from wikis
Findability / organizing content
From overlooked to center stage
Java notes
JavaScript notes
DITA notes
Podcasts
I'd Rather Be Writing Podcasts
Tech comm podcasts
Email Newsletter
Subscribe to my newsletter
Newsletter signup
×
Documenting APIs
Collapse All
|
Expand All
I: Introduction to REST APIs
Section Overview
Course Overview
What's new
Workshop video recordings
Download PDFs
Workshop agenda, slides, activities
Why I developed this course
About the author
Introduction to REST API documentation
What is a REST API?
Activity: Identify your goals
Developer Documentation Trends: Survey Results
Glossary
II: Using an API like a developer
Section Overview
Scenario for using a weather API
Get authorization keys
Submit requests through Postman
curl intro and installation
Make a curl call
Understand curl more
Activity: Use methods with curl
Analyze the JSON response
Inspect the JSON from the response payload
Access and print a specific JSON value
Dive into dot notation
III: Documenting API endpoints
Section overview
A new endpoint to document
API reference tutorial overview
Step 1: Resource description
Step 2: Endpoints and methods
Step 3: Parameters
Step 4: Request example
Step 5: Response example and schema
Putting it all together
Activity: What's wrong with this API reference topic
Activity: Evaluate API reference docs for core elements
IV: OpenAPI spec and generated reference docs
Section overview
Overview of REST API specification formats
Introduction to the OpenAPI specification
Stoplight: Visual modeling tools for creating your spec
Getting started tutorial: Using Stoplight Studio to create an OpenAPI specification document
Swagger UI tutorial
SwaggerHub introduction and tutorial
Swagger UI Demo
Integrating Swagger UI with the rest of your docs
Redocly tutorial -- authoring and publishing API docs with Redocly's command-line tools
Redoc Community Edition Basic Demo
V: Step-by-step OpenAPI code tutorial
Section overview
OpenAPI tutorial using Swagger Editor and Swagger UI: Overview
Working in YAML
Step 1: The openapi object
Step 2: The info object
Step 3: The servers object
Step 4: The paths object
Step 5: The components object
Step 6: security object
Step 7: The tags object
Step 8: The externalDocs object
Activity: Create an OpenAPI specification document
VI: Testing API docs
Section overview
Overview of testing your docs
Set up a test environment
Test all instructions yourself
Test your assumptions
Activity: Test your project's documentation
VII: Conceptual topics in API docs
Section overview
API conceptual topics overview
API product overviews
API getting started tutorials
API authentication and authorization
API status and error codes
API rate limiting and thresholds
API quick reference
API glossary
API best practices
Activity: Complete the SendGrid Getting Started tutorial
Activity: Assess the conceptual content in your project
VIII: Code tutorials
Section overview
Common characteristics of code tutorials
Why documenting code is so difficult
What research tells us about documenting code
Five strategies for documenting code
Code samples
Sample apps
SDKs (software development kits)
API design and usability
Developer experience (DevX) usability
IX: The writing process
Section overview
Overview of the writing process
1. Planning
2. Information gathering
3. Writing
4. Reviewing
5. Publishing
X: Publishing API docs
Section overview
Overview for publishing API docs
Survey of API doc sites
Design patterns with API doc sites
Docs-as-code tools
More about Markdown
Version control systems (e.g., Git)
Activity: Manage content in a GitHub wiki
Activity: Use the GitHub Desktop Client
Activity: Pull request workflows through GitHub
Static site generators
Hosting and deployment options
Hybrid documentation systems
Using Oxygen XML with docs-as-code workflows
Blobr: An API portal that arranges your API's use cases as individual products
Which tool to choose for API docs — my recommendations
Jekyll and CloudCannon continuous deployment tutorial
Case study: Switching tools to docs-as-code
Tools FAQ
XI: Thriving in the API doc space
Section overview
The job market for API technical writers
How much code do you need to know?
Best locations for API documentation jobs
Activity: Find an Open-Source Project
Activity: Create or fix an API reference documentation topic
XII: Native library APIs
Section overview
Overview of native library APIs
Get the sample Java project
Java crash course
Activity: Generate a Javadoc from a sample project
Javadoc tags
Explore the Javadoc output
Make edits to Javadoc tags
Doxygen, a document generator mainly for C++
Create non-ref docs with native library APIs
XIII: Processes and methodology
Section overview
DX content strategy with developer portals
Following agile scrum with documentation projects
Managing large documentation projects
Managing small documentation requests
Managing SDK releases
Documentation kickoff meetings and product demos
Processes for reviewing documentation
Maintaining existing documentation
Collecting feedback post-release
Managing content from external contributors
Changing internal doc culture
Sending doc status reports -- a tool for visibility and relationship building
Broadcasting your meeting notes to influence a wider audience
Ensuring documentation coverage with each software release
XIV: Metrics and measurement
Section overview
Measuring documentation quality through user feedback
Different approaches for assessing information quality
Quality checklist for API documentation
Quantifying your progress
XV: Additional resources
Section overview
Documenting GraphQL APIs
More REST API activities
Activity: Get event information using the Eventbrite API
Activity: Retrieve a gallery using the Flickr API
Activity: Get wind speed using the Aeris Weather API
RAML tutorial
API Blueprint tutorial
API jeopardy answer key
What's wrong with this topic answer key
Menlo Park API workshop video recording
Denver API workshop video recording
API doc presentation video recordings
Search results
I'd Rather Be Writing
Learn API Doc
Table of Contents
Last updated: Nov 02, 2020
Start AI Chat
GPT Chat by Markprompt
×
Buy me a coffee
Please enable JavaScript to load the comments.
© 2023 Tom Johnson