An API design reference kit is a collection of information and artifacts that fully describes an API. It supports collaborative design and supplies an essential input for implementation and testing, while remaining useful throughout the API lifecycle. section 1.6.4 section 19.1
Build the kit around the API’s capabilities and adapt its contents to the context:
- Capture needs, users, use cases, concepts, operations, and operation flows with an API Capabilities Canvas. section 19.1.1
- Describe paths, methods, data, behavior, errors, and security with an OpenAPI document. section 19.1.1
- Define the API’s general look and behavior through design guidelines, an OpenAPI library, and linting rules. section 1.7.4 section 19.1.1
- Add JSON Schema precision, examples, implementation notes, mocks or prototypes, and functional tests when they provide useful support. section 19.1.7 section 19.8
A practical baseline
Start with an API Capabilities Canvas, an OpenAPI document, and design guidelines. Enrich the kit with documented request and response examples, a static mock for development, and functional tests that check whether the implementation matches the design. For public or partner APIs, use these artifacts to create portal documentation and a playground; for private APIs, provide the raw kit or documentation generated from it. section 19.1.6 section 19.1.7
Figure 19.1 Although “Enrich API design artifacts” is the final step in the sequential design process diagram, we work on the API design reference kit across all the steps. Its content is helpful during design and the subsequent API lifecycle stages.
Use the lifecycle view to see why the kit is crafted across the design process rather than only at its final step. section 19.1
