19 Enriching API design artifacts

This chapter covers

Adding an overview of the API, concepts, and use cases
Sharpening data models
Illustrating data, operations, and flows with examples
Enhancing or adapting artifacts for implementers
Considering a simulated or a prototyped API
Considering API functional tests

Artifacts such as the filled API Capabilities Canvas (refining initial user needs), the OpenAPI document (describing the API), and our API design guidelines, including the OpenAPI library and linting rules (detailing the API’s standard look and behavior), help us design, discuss, review, and document an API that matches expectations. These artifacts form the core of an “API design reference kit” that serves as support and a deliverable of the API design process and is helpful across the entire API lifecycle.

In addition to supporting us during design, the API design reference kit is essential to help developers (who may be us) implement, test, and deploy the API accurately and efficiently. This kit can also be a base for the elements available on a public API portal to help third-party developers create applications that consume the API. In the case of private APIs, the API design reference kit will likely be the only resource available for developers (who may also be us) using the API.

19.1 Crafting an API design reference kit

19.1.1 What an API design reference kit can contain

19.1.2 Using the kit to design the API

19.1.3 Using the kit to develop the API

19.1.4 Using the kit to test the API

19.1.5 Using the kit to deploy the API

19.1.6 Using the kit to provide and consume the API

19.1.7 What we already have and what we may want to add

19.2 Providing an overview of the API design with OpenAPI

19.2.1 Adding links to other artifacts and describing the API

19.2.2 Organizing operations around concepts and use cases

19.2.3 Describing use cases

19.3 Enhancing the precision of data models with JSON Schema

19.3.1 Describing a number or element size range

19.3.2 Describing a value with pattern, enum, and default

19.4 Providing examples to illustrate data and operations

19.4.1 Adding property examples with JSON Schema

19.4.2 Adding examples of parameters, request and response bodies, and headers with OpenAPI

19.7.1 Clarifying logic