The short version

The Arazzo Specification is an add-on to the OpenAPI Specification. The Open API Specification deals with description of rest endpoints, whereas the Arazzo Specification deals with describing a sequence of calls to these endpoints to reach certain outcomes. For example:

While an OpenAPI Spec can describe rest API endpoints like LoginUser and GetUserProfileData, an Arazzo Spec can describe a sequence of steps to be able to get an authentication token from the LoginUser endpoint and send it in the header of a request to the GetUserProfileData endpoint to get User Profile Data. equest to the GetUserProfileData endpoint to get User Profile Data.

—————————————————————

Introduction

The OpenAPI Initiative website calls Arazzo the first “additional” specification from OpenAPI. It is only the second specification released by them after the original and popular OpenAPI Specification.

What is an Arazzo Specification?

We already know that an OpenAPI Specification is used to describe HTTP endpoints in a human as well as machine readable standardized format. Building on top of this foundation, an Arazzo Specification can describe Workflows i.e. a sequence of calls to these endpoints to reach one or many desired outcome.

What is the purpose of Arazzo?

With the introduction of OpenAPI Specifications, it has been possible to describe HTTP endpoints in great detail. We can describe the expected parameters, examples, expected outputs, rest operation, response codes and much more for an endpoint. While this standardization has been extremely useful when looking at endpoints individually, it has not been possible to describe how these endpoints work in tandem with one another. This is where the Arazzo framework comes in.

Now, developers and technical writers will be able to describe human & machine readable endpoint “workflows” in a standardized format.

Example of an Arazzo workflow

Let’s say there is a service that can tell you the current temperature in any city around the world. In order to use this service, a user first has to retrieve an authorization token by logging in.

An Arazzo specification can illustrate the above requirement in a structured workflow. Below is a stripped down illustrative version of the Arazzo Specification “Steps” for a workflow where a user intends to fetch the current temperature in Mumbai. Descriptive comments have been added to the YAML to make it easy to understand.

img

steps:
  - stepId: stepToLoginUser # A unique identifier for this step
    description: Login user into the system
    operationId: userLogin # This is an operationId from within a referred OpenAPI spec
    parameters: # The params that will go with the request to the endpoint described by the above operationId
      - name: username
        in: query
        value: $inputs.username # $inputs is a runtime expression which refers to a
                                                        # JSON passed to the Workflow that containes this step
      - name: password
        in: query
        value: $inputs.password
    successCriteria:
      - condition: $statusCode == 200
    outputs: # outputs from this step
        tokenExpires: $response.header.X-Expires-After
        authorizationToken: $response.body # This is referred in the next step under parameters
  - stepId: getTemperatureOfCity # A unique identifier for this step
    description: Fetch city temperature from GET endpoint
    operationPath: '{$sourceDescriptions.weatherDataOpenAPISpec.url}#/paths/~1getCityTemperature/get'
    # Similar to operationId present in the previous step, operationPath also refers to a specific endpoint from
    #  within a referred OpenAPI spec
    parameters: # The params that will go with the request to the endpoint described by the above operationPath
      - name: country
        in: query
        value: 'India'
      - name: city
        in: query
        value: 'Mumbai'
      - name: Authorization
        in: header
        value: $steps.userLogin.outputs.authorizationToken # This is received from the previous step viz. "stepToLoginUser"
    successCriteria:
      - condition: $statusCode == 200
    outputs:
        currentTemperature: $response.body.temperature # output from this step

Here is a diagram to visually explain the workflow:

(Interestingly, the above diagram could have been auto-generated by a tool that can parse an Arazzo Spec)

Why is something like the Arazzo Specification needed?

Before Arazzo there was no standardized method of describing API call sequences to reach a particular set of outcomes. If you maintain API services, till now the only way to describe how to use these services in tandem has been to manually write examples in end user documentation. Additionally, any changes to endpoints within your services makes it necessary to go and edit these documents manually.

With the advent of the Arazzo Specification the following will become possible,

• Interactive user interfaces that document these workflows

• Automated documentation generation

• Tools that give developers the ability to describe workflows within code

• Automated test generation for workflows

• Client Code generation for workflows

• AI Agents/LLMS deterministically using APIs without prior training on the API

For more information, check out the detailed Arazzo Specification here