What are APIs and What's Up with API Documentation?

Goals

• Understand the different kinds of APIs.
• Understand how APIs are useful.
• Understand how documentation helps users with APIs.

Watch

• Comparing web API types: SOAP, REST, GraphQL and RPC
• What is an API? Connections and principles explained
• API Documentation and Why it Matters

Read

• The Design of Web APIs
  • Ch. 1: What is API design?
  • Ch. 2: Designing an API for its users
• Designing APIs with Swagger and OpenAPI
• Ch. 1: Introducing APIs and OpenAPI
• Tom Johnson's Introduction to REST APIs

How Can Technical Writers Interact with APIs?

Goals

• Create an account with Postman.com to start interacting with APIs.
• Follow this tutorial to learn how to navigate Postman and send requests to an API.
• Understand how requests and responses work conceptually, along with the four main REST API verbs:
• GET
• POST
• PUT
• DELETE
• Understand the role technical writers play in API documentation.
• Understand curl.

Watch

• POSTMAN BEGINNER TUTORIAL 1 - Introduction | What is POSTMAN

Read

• The Design of Web APIs
  • Ch. 3: Designing a Programming Interface
• Designing APIs with Swagger and OpenAPI
• Ch. 2: Getting set up to make API requests
• Tom Johnson's Using an API Like a Developer

What's a Back End, and How Does an API Function?

Goals

• Follow directions to build a simple full stack application. By building it, you can interact with the API and see its parts working.
• Take the Codecademy class Designing and Documenting an API with Swagger.
  • NOTE: This requires a paid subscription to Codecademy.
• Understand how an application can be derived from the specification, and vice versa.

Watch

• MERN Stack Tutorial #1 - What is the MERN Stack?

What Is OAS and How Does It Help Us Write API Docs?

Goals

• Understand what the Swagger/OAS Specification is and how it works.
• Start writing a specification with Swagger.

Watch

• REST API and OpenAPI: It's Not an Either/Or Question

Read

• The Design of Web APIs
• Ch. 4: Describing an API with an API description format
• Ch 5: Designing a straightforward API
• Designing APIs with Swagger and OpenAPI
• Ch. 3: Our first taste of OpenAPI definitions
• Ch. 6: Creating resources
• Tom Johnson's OpenAPI spec and generated reference docs

How Can Technical Writers Author and Publish a Specification?

Goals

• Write a complete OpenAPI specification for a fictional API.
• Publish the specification on at least one platform.
• Use another tool besides Stoplight to publish your specification
• OpenAPI.Tools

Watch

• Demo: Stoplight Studio Basics
• Document a REST API with OpenAPI and Stoplight Studio

Read

• Tom Johnson's Using Stoplight Studio to create an OpenAPI specification document
• Tom Johnson's Swagger UI Tutorial
• Designing APIs with Swagger and OpenAPI
• Ch. 6: Creating resources
• Ch. 8: Preparing and hosting API documentation
• Ch. 9: Designing a web application
• The Design of Web APIs
• Ch. 12: Documenting an API