Chapter 5: Describing APIs
Design and Build Great Web APIs — by Mike Amundsen
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.
Learning the Role of Description Formats
It is important to have a shared description of the API because API designers and API builders may not always have a chance to talk to each other directly.
Another handy aspect of description formats is that they don’t depend on any single technology, document format or API style. They simply describe the data to be passed back and forth and the actions that should be available.
API descriptions provide enough information to tell everyone what must be done, but they leave the how of doing it up to the API developers.
Description vs Definition
The dictionary definition of description is “a statement or account giving the characteristics of someone or something: a descriptive statement or account.” The role of an API description is to do just that: give the characteristics of the API we’re working on together.
The dictionary defines definition as a “statement expressing the essential nature of something”. In the API world, expressing the essential nature of the API means including all the details used in implementing it.
Descriptions give us a general view of the API — its outline or profile — without getting bogged down in the details.
Dublin Core Application Profile (DCAP)
One of the most mature of the description formats is the Dublin Core Application Profile or DCAP specification. The DCAP spec is pretty complex and not all is covered in this book. However here is a small example of it —
Application-Level Profile Semantics (ALPS)
The ALPS description format was designed to help API designers and developers easily and accurately share information needed to create APIs for the web. For this reason, the ALPS format emphasizes the ability to do something — to describe an action along with the data properties to pass with these actions.
This wraps the design portion of this book and we will start building APIs in the next phase.
