Table of Contents
- I: Introduction to REST APIs
- Course Overview
- What's new
- Workshop video recordings
- 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
- 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
- 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
- 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
- OpenAPI tutorial using Swagger Editor and Swagger UI: Overview
- Working in YAML
- Step 1: The openapi object (OpenAPI tutorial)
- Step 2: The info object (OpenAPI tutorial)
- Step 3: The servers object (OpenAPI tutorial)
- Step 4: The paths object (OpenAPI tutorial)
- Step 5: The components object (OpenAPI tutorial)
- Step 6: security object (OpenAPI tutorial)
- Step 7: The tags object (OpenAPI tutorial)
- Step 8: The externalDocs object (OpenAPI tutorial)
- Activity: Create an OpenAPI specification document
- VI: Testing API docs
- 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
- 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
- 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
- Overview of the writing process
- 1. Planning
- 2. Information gathering
- 3. Writing
- 4. Reviewing
- 5. Publishing
- X: Publishing API docs
- 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
- 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
- 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
- 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
- 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
- Ensuring documentation coverage with each software release
- XIV: Metrics and measurement
- Measuring progress against documentation quality goals
- First-level checklist for API documentation
- Second-level checklist for API documentation
- Quantifying your progress
- Templates for working with metrics
- XV: Additional resources
- 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
