Summary

This chapter reviewed a number of things related to documenting our API design in both machine-readable and human-readable formats. Along the way, we covered the importance of implementation-agnostic description formats for converting our diagrams into other formats, and the difference between general description formats and implementation-specific definition formats.

We also reviewed both the Dublin Core Application Profile (DCAP) and the Application-Level Profile Semantics (ALPS) formats.

In addition, we worked through the process of describing our Onboarding API using ALPS. That included adding the title and general documentation text, adding all the vocabulary from our design session, organizing the response data into shorthand names, describing all possible state transitions in the API, and providing added detail to all the state transitions. We also learned to add the resulting ALPS description document to our API project folder and updated the package.json file.

Later, we learned how to apply a simple API design method as a way to gather important information about the planned user experience. This included collecting not just data names, but also information about actions taken with that data. We then learned how to normalize our data names using ontologies like Schema.org as well as how to use the WebSequenceDiagrams (WSD) service to turn our design results into a visual that’s easy to read and share with others.

Now that we’ve translated that visual design information into both human-readable HTML and machine-readable ALPS data, we’re ready to start actually building an API from the ground up.