Design and Build Great Web APIs

Describing Your API with ALPS

Recall from Chapter 4, ​Designing APIs​, that we designed the onboarding experience and documented it using, among other things, a sequence diagram, as shown in the figure.

We can use this diagram, along with the data properties we outlined, as a guide to create an ALPS description document for our API (see Table 1).

The work of authoring an ALPS document is the process of converting the diagram (along with the property information) into a machine-readable format. This format can then be used to generate basic human-readable documentation, as well as some “starter” code for our implementation.

Table 1. Onboarding Properties ...