Design and Build Great Web APIs

Chapter 5Describing APIs

This chapter focuses on turning the design information we gathered in the previous chapter into a comprehensive, machine-readable format that can be used as a guide for creating a working instance of the API itself. The same information can be used to generate basic (low-level) human-readable API documentation.

First, we’ll cover the importance of API descriptions as a way to standardize the way we talk about the API independent of the way we implement the API (for example, protocols, formats, URLs, and so on). We’ll also briefly cover two of the most commonly used description formats: DCAP (Dublin Core Application Profiles) and ALPS (Application-Level Profile Semantics). Finally, we’ll walk through the process ...