Making Sure All Your Enterprise Capabilities Are Well Defined

The final, and most critical element of any enterprise API toolbox, is ensuring that all of your enterprise capabilities are defined as machine-readable API contracts, using OpenAPI, AsyncAPI, JSON Schema, and other formats. API definitions should provide human and machine-readable contracts for all enterprise capabilities that are in play. These contracts contribute to every stop along the API lifecycle, and help both API providers and consumers realize what they are looking to accomplish by delivering APIs across their large organizations.

OpenAPI provides what we need to define our request and response capabilities using HTTP, and Async provides what we need to define our event-driven capabilities, providing the basis for understanding what we are capable of delivering using our API toolboxes, and responding to via the hybrid integration solutions we’ve engineered, and automated using our event-driven solutions. Defining the surface area of our API infrastructure, but also the API operations that surround the enterprise capabilities we are enabling internally, with partners, and publicly via our enterprise API efforts.

While OpenAPI has emerged as the dominate format for defining the surface area of your API infrastructure, there are other companion, and compatible formats that also help connect the dots. The center of the contract should always be OpenAPI definitions, but Postman Collections, .HAR files, JSON Schema, and other artifacts have a role to play in defining how are infrastructure evolves. It is impossible to to properly manage and evolve API infrastructure that isn’t quantified and defined. If there is not a complete definition of what an API delivers, and how it fits into the bigger picture, it may as well not exist. Making it critical that all enterprise capabilities are well defined using common API definition formats, and available in a central catalog and directory for continual evaluation as part of the bigger picture and API strategy.