The Arazzo Specification: A Tapestry for API Workflows

A presentation at APIDays Helsinki and North in in Helsinki, Finland by Frank Kilcommins

Officially announcing the Arazzo Specification which enables the ability to define and document workflows, a series of API calls, that when woven together accomplish a specific business objective. The new specification was developed under the OpenAPI Initiative, and complements current specifications, including OpenAPI and AsyncAPI.

Arazzo provides a deterministic recipe for using APIs and enables code generation tooling for a given API based on use-cases. Additionally, Arazzo improves regulatory checks and bridges gaps where use-case flows span multiple API descriptions.

The new specification provides a sufficient level of predictable determinism to AI models, allowing them to offer a natural language abstraction on top of the business use cases, while in parallel giving interoperability benefits to the actual API providers. The result is more value, with less vendor lock-in, and consistent API offerings for both humans and the new wave of AI consumers.

In general, there’s enormous potential to enhance the developer experience (DX) and API documentation by enabling graphical rendering of API workflows. The specification also improves human understanding of how to consume API endpoints to achieve a specific goal.

Arazzo descriptions can stay up-to-date and be assertable against the underlying APIs. This reduces the need for out-of-band documentation sharing, reduces the time and effort required to implement complex workflows, and automates testing and other repetitive tasks. Overall, the Arazzo Specification improves the capability of API specifications to tell the story of the API in a manner that improves interoperability across industries.



The following resources were mentioned during the presentation or are useful additional information.