API reference documentation is not usually considered sexy, but it can address a large number of minute decisions facing client developers. After recalling the base concepts of REST APIs, this session shows how to create a diagram that visualises the relationships between API operations and API definitions. The visualisation allows technical communicators to chunk the API into cohesive pieces for explanation. Then, the session focuses on the sequence of decisions facing a client developer that is trying to use a REST API. Any of these small decisions can interrupt a developer by forcing a lengthy investigation or a support request. Drawing upon the Open API standard for describing REST APIs, technical communicators can guide these small decisions by writing suitable focused descriptions in the right places.

While the approach described in the session applies to any kind of API, examples will use REST API concepts.

By the end of this session you will learn to:

• Create UMLish diagrams of REST APIs that visualise the relationships between operations and definitions. Identify the decisions of client developers, and how descriptions in Open API specifications can address their needs.
• Recognise ambiguous and incomplete specifications.

Reference

Presentation slides

Local copy of the slides for the presentation, stripped from the fashion photos commissioned by Farfetch for the 2023 autumn/winter season.