From April to September of 2018, the STC Arizona Chapter hosted a series of application programming interface (API) documentation webinars for technical communicators and students who wanted to learn more about documenting Representational State Transfer (REST) APIs.
We used Tom Johnson’s (outstanding) Documenting APIs, a Guide for Technical Writers as our course material. Tom developed the free, self-paced course specifically for technical communicators (thanks, Tom!).
The following participants completed the course material:
- Tessa Audet
- Monique Dawson
- Kim Jones
- Judith Mieyr
- Francisco Moran
- Doug Ryan
- Tony Sabal
- Eric Strachan
- Alan Vickers
What We Learned
Some of topics we covered included:
- How REST services are used in data transfers.
- How to use cURL and Postman to make REST calls.
- How to write API documentation non-reference topics such as a content overview, requirements for authentication and authorization, and how to get started using the services.
- How to write reference documentation that includes the REST structure, endpoint parameters, and schema definitions.
- How to use Swagger UI and YAML files to create documentation.
API Documentation Website
To demonstrate a working knowledge of the course material, the participants developed an example API business model website.
The website includes sections for reference and non-reference documentation uses YAML files to display reference documentation in Swagger UI.