Thank you for donating
Thank you for donating. Your support helps drive more time and energy into this course and also helps make this course available online for free.
Tom Johnson
Email Newsletter
Newsletter signup
Documenting APIs
- 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
- 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
- IX: The writing process
- 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
- 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
- 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
Recent posts
- Blog and API doc course are now one site (Jun 9, 2023)
- Doctave Q&A with Niklas Begley (Jun 8, 2023)
- News turns the content wheel of advertising (May 19, 2023)
- Review of WordTune: Granular style checkers still beat Bard and ChatGPT (May 19, 2023)
- Newsletter: Endless news cycles, style checkers, finding research, noticing things around you (May 19, 2023)
- How to find academic research to back up your tech comm decisions (May 19, 2023)
- Book review of the Art of Noticing, by Rob Walker (May 19, 2023)
- AI starting to diminish work for student essay ghostwriters (May 19, 2023)
- From DITA to docs-as-code and Docusaurus: Q&A with Mike Howes (May 16, 2023)
- Newsletter: Copilot for Docs, Wappalyzer, Illusions, Late projects, Forbidden Fruit (May 11, 2023)
Popular series
- Trends to follow or forget
- Sitting, standing, and walking
- Journey away from smartphones
- A hypothesis about influence on the web and the workplace
- Simplifying complexity
- Reflecting seven years later about why we were laid off
- Value arguments for docs and tech comm
- Innovation in tech comm
- Get a job in technical writing
Search results
