The Arazzo Specification is a community-driven open specification within the OpenAPI Initiative, a Linux Foundation Collaborative Project.
The Arazzo Specification defines a standard, programming language-agnostic mechanism to express sequences of calls and articulate the dependencies between them to achieve a particular outcome, or set of outcomes, when dealing with API descriptions (such as OpenAPI descriptions).
The Arazzo Specification can articulate these workflows in a deterministic human-readable and machine-readable manner, thus improving provider and consumer experiences when working with APIs. Similar to what OpenAPI has done for describing HTTP interfaces, the Arazzo Specification enables the ability to articulate the functional use cases offered by an API (or group of APIs) thus removing the guesswork for both human and machine consumers.
Use cases for machine-readable API workflow definition documents include, but are not limited to:
The Arazzo Specification does not mandate a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear workflow interactions with HTTP APIs described using the OpenAPI Specification.
This GitHub project is the starting point for Arazzo. Here you will find the information you need about the Arazzo Specification, simple examples of what it looks like, and some general information regarding the project
A major cost contributor to consuming travel retail APIs is the lack of workflow documentation and the overall lack of automation. API consumers largely depend on trail and error testing to sort out how any one API works given just the schema to look at, but sorting out the sequence of APIs is a nightmare. Travel APIs could certainly benefit from the original OpenAPI spec which define how one creates a description document allowing more context about what an API does than just JSON message schema.
Let me make that more clear, the API description document (OAS 3.1 is the latest version) itself is written in schema (JSON or YAML) so it is machine readable. Not for the purpose of sending some data in a message but to describe the API. From that description, many API dev tools create the message and often some software as needed (code generation). Two documents for different purposes. One to describe the API and another to define the message that will be used to move data.
Arazzo in a similar way is machine readable (YAML) but defines a group of APIs. What sequence are they to be called in and what data elements are to be passed back and forth. A workflow is organized into steps with definition of success and failure. Those of a certain age will see the similarities with scripting and other workflow concepts that have been around for decades. An API provider can publish their Arazzo description as part of their API based product release. Think of it as a form of product description as it explains how the collection of APIs delivers the product.
Tool providers are already working on future product release which will use the Arazzo description to automate API consumption. A fair amount of this will be code generation. This will have a dramatic affect on reducing the labor and time needed to get APIs producing revenue. If the API consumer does not need endless hours and tons of testing to figure out how to use a collection of APIs, and tools generate most of the code needed, they can compress the timeline to production.
For more information on the OpenAPI Initiative and #sig-travel, join the conversation on slack. https://open-api.slack.com/archives/C0122NPKUR2
If you need a slack ID, go to: https://join.slack.com/t/open-api/signup