Weave API workflow using Arazzo: OpenAPI’s new Spec

3 min readJun 18, 2024

The Open API Specification (OAS) (widely known as Swagger docs) has been widely adopted for describing RESTful APIs. However, one limitation is that it lacks a native way to group a series of API calls together in a machine-readable manner. The primary method for grouping is using OperationID, but this approach isn’t very explicit or machine-friendly. Hence, to address this issue Arazzo was born.

What Arazzo Spec is (and isn’t)

The Arazzo specification groups a series of APIs that are part of the same workflow. It provides a standard, programming language-agnostic mechanism to express sequences of API calls and their dependencies. Arazzo allows you to weave together these calls, articulating the relationships between them. Here’s what Arazzo is:

Arazzo Is: A mechanism for defining sequences of calls and expressing their dependencies within the context of API descriptions (such as OpenAPI descriptions).
Arazzo Is Not: A replacement for OpenAPI; rather, it complements it by enhancing the way we describe API interactions.

Getting Started with Arazzo

To start using Arazzo, you need to create a separate file for your Arazzo specification. Like OAS, Arazzo specifications are typically written in YAML or JSON. And, you don’t need a pre-written OpenAPI description to create an Arazzo spec, but having one can help you map your API calls effectively.

How to Structure Arazzo Specification

Arazzo specification isn’t drastically different from the way you write OAS. However, the initiative has determined the need to introduce a few new objects to make the workflow possible. The diagram below shows a high level overview of how the specification is structured.

*Source:* *https://github.com/OAI/Arazzo-Specification/*

The key elements of the these structure are:

Structured Sequences: Arazzo allows you to define the workflow of API calls explicitly, making it easier to understand the flow.
Dependencies: You can express dependencies between calls, ensuring proper execution order using the step objects.
Outcome-Oriented: Arazzo focuses on achieving specific outcomes by weaving together calls as shown by the successCriteria and outputs objects.

As for an example of the specification itself, see below.

  arazzo: 1.0.0

  info:
    title: My Awesome API Workflow
    version: 1.0.0

  sourceDescriptions:
  - name: petStoreDescription
    url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml
    type: openapi

  workflow:
  - workflowId: loginUserAndRetrievePet
    summary: Login User and then retrieve pets
    inputs:
        type: object
        properties:
            username:
                type: string
            password:
                type: string

    steps:

      - stepId: loginStep
        operationId: loginUser
        parameters:
          - name: username
            in: query
            value: $inputs.username
          - name: password
            in: query
            value: $inputs.password
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          tokenExpires: $response.header.X-Expires-After
          rateLimit: $response.header.X-Rate-Limit
          sessionToken: $response.body

      - stepId: getPetStep
        description: retrieve a pet by status from the GET pets endpoint
        operationPath: '{$sourceDescriptions.petstoreDescription.url}#/paths/~1pet~1findByStatus/get'
        parameters:
          - name: status
            in: query
            value: 'available'
          - name: Authorization
            in: header
            value: $steps.loginUser.outputs.sessionToken
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          # outputs from this step
          availablePets: $response.body

      outputs:
          available: $steps.getPetStep.availablePets

Get Ready for Arazzo

The Arazzo Specification empowers developers to create more expressive and outcome-oriented API descriptions. By weaving together calls and articulating dependencies, Arazzo enhances the way we design and document APIs.

Hungry for More?

If you’re eager to dive deeper into the Arazzo Specification, here are some resources to explore:

Remember, Arazzo doesn’t replace OpenAPI — it complements it, making our API descriptions more powerful and machine-friendly.

Struggling with your tech docs

If you find yourself grappling with documenting APIs and technical information within your organization, you’re not alone. Clear and effective documentation is crucial for showcasing your full potential.

Reach out to us if you need help with your technical documentation and be sure to leave your opinion and insights.