The Arazzo Specification: A New Era for API Workflow Documentation

APIs have become the backbone of modern software development, enabling seamless communication between diverse systems. Yet, as APIs grow in number and complexity, understanding how to orchestrate multiple API calls into coherent workflows remains a significant challenge. Enter the Arazzo specification, a groundbreaking approach designed to describe API workflows deterministically across the modern API stack.

Developed under the umbrella of the Open API Initiative and championed by Frank Kilkomins, Principal API Technical Evangelist at SmartBear, Arazzo offers an innovative solution to document use case-oriented APIs in a programmatically readable format. This article delves deep into the Arazzo specification, its architecture, use cases, and the transformative potential it holds for API consumers, providers, and the broader ecosystem.

Understanding Arazzo: The Missing Piece in API Workflow Management

Arazzo, which means “tapestry” in Italian, aims to weave together a series of API calls into meaningful workflows that achieve specific business objectives. Unlike traditional API documentation, which often focuses on individual endpoints, Arazzo provides a way to describe a sequence of calls and their interdependencies in a structured, machine-readable format using JSON or YAML.

At its core, Arazzo helps developers and API consumers understand not just what an API does in isolation, but how multiple API calls combine to deliver a complete, use case-oriented experience. This is particularly crucial in today’s complex environments where business processes often span multiple APIs and services.

Why Arazzo Matters

• Deterministic Workflow Description: Arazzo enables the explicit documentation of API call sequences to accomplish specific outcomes, reducing guesswork for developers.
• Improved Developer Experience: By narrating the story of an API workflow, developers can onboard faster and integrate APIs more effectively.
• Bridging Multiple APIs: Workflows can span across different APIs, tying them together into a cohesive operational flow.
• Living Documentation: Arazzo helps keep documentation in sync with API changes, preventing stale or misleading guides.
• Assertable Business Value: It allows for validation and testing of workflows to ensure business objectives are met even as APIs evolve.
• Optimized SDK and Code Generation: SDKs can be generated around specific workflows rather than entire API surfaces, reducing bloat and improving usability.
• Regulatory and Compliance Support: Arazzo facilitates regulatory validation by explicitly defining expected workflows and behaviors.
• Support for AI-driven API Consumption: With deterministic workflows, AI agents can reliably invoke APIs without errors or hallucinations.

The Challenges Arazzo Addresses

Many developers have experienced the frustration of onboarding to a new API where the documentation is overwhelming or incomplete. Large OpenAPI specifications with hundreds of endpoints make it difficult to discern the order of calls necessary to achieve business goals. Additionally, when workflows span multiple APIs—each possibly documented separately—consumers lack a unified artifact to guide their integration efforts.

Documentation outside of the API specs, such as HTML pages, videos, or PDFs, often become outdated as APIs evolve. This disconnect leads to confusion, errors, and increased support burden. Arazzo aims to solve these issues by providing a single source of truth that is both human-readable and machine-interpretable.

Inside the Arazzo Specification: Structure and Components

If you’re familiar with OpenAPI or AsyncAPI, you’ll find Arazzo’s structure intuitive. It organizes workflows into a clear and concise format, enabling both humans and tools to understand the intended API interactions.

Core Elements of an Arazzo Document

• Info Object: Contains metadata about the Arazzo document, such as the title, version, summary, and description. This is akin to the info section in OpenAPI documents.
• Source Descriptions: These are references to the APIs or other Arazzo workflows involved in the current document. Think of them as imports or namespaces that set the boundaries for the workflows described.
• Workflows: The heart of the specification, workflows describe a sequence of steps to achieve a business objective. Each workflow includes an ID, summary, description, inputs, parameters, steps, success and failure actions, and outputs.
• Steps: Each step represents either an API operation call or invocation of another workflow. Steps include parameters, success criteria, failure criteria, outputs, and control flow mechanisms such as dependencies.
• Parameters: Define how inputs are mapped into API operation parameters, such as query parameters or headers.
• Success and Failure Actions: Define what to do when a step succeeds or fails. These can include retries, ending the workflow, or jumping to other steps or workflows.
• Outputs: Map dynamic values from steps to named outputs that can be used in subsequent steps or returned to the caller.
• Components: Reusable objects and definitions to reduce verbosity and promote consistency across workflows.

Example: The Info Object

Here’s a simple YAML snippet illustrating the info object:

arazzo: 1.0.0
info:
  title: Buy Now Pay Later Workflow
  summary: Workflow to enable BNPL integration for retailers
  description: This workflow describes the steps to verify eligibility, initiate loans, and fulfill orders.
  version: 1.0.0

Source Descriptions Explained

Source descriptions serve as the foundational references for the APIs involved in the workflows. They ensure that any API operation referenced within a workflow is valid and corresponds to an existing API description. For example, you might see something like this:

sourceDescriptions:
  - url: https://api.example.com/petstore/openapi.yaml
    type: openapi
  - url: https://api.example.com/adoptions/openapi.yaml
    type: openapi

This setup declares two APIs—Petstore and Adoptions—that can be invoked within the workflows defined in this Arazzo document.

Defining Workflows and Steps

Workflows are composed of ordered steps, each representing a call to an API or another workflow. Steps include detailed parameters, success criteria, failure handling, and outputs.

Step Parameters

Parameters define how data flows into an API call. For instance, mapping an input value to an API’s query parameter can be described as:

parameters:
  - name: category
    in: query
    value: ${inputs.productCategory}

This means that the “category” query parameter of the API is dynamically set based on the workflow’s input named “productCategory.”

Success and Failure Criteria

Each step includes criteria to determine if it was successful or failed. For example, a step might be considered successful if the API returns a 200 status code and a response body contains more than one pet:

successCriteria:
  - statusCode == 200
  - responseBody.pets.length > 1

If these conditions aren’t met, failure actions can be triggered, such as retrying the call after a delay, ending the workflow, or jumping to a different step. For instance, a retry failure action might look like this:

failureActions:
  - type: retry
    retryAfter: 1s
    retryLimit: 5
    criteria:
      - statusCode == 503

Control Flow Between Steps

Arazzo allows workflows to include dependencies between steps, enabling conditional execution and branching. Success actions can also direct the workflow to jump to specific steps based on outcomes, providing flexibility in managing complex business logic.

Real-world Example: Buy Now, Pay Later Workflow for Student Retailers

To illustrate the power of Arazzo, imagine a free-debt student bank partnering with retailers to offer a Buy Now, Pay Later (BNPL) product. With students returning to university, retailers want to provide zero-interest loans on essential equipment like laptops and software.

The BNPL workflow might include the following steps:

1. Verify that selected products in the shopping basket are eligible for BNPL.
2. Retrieve terms and conditions and determine customer eligibility.
3. Create a new customer record if the customer is unknown.
4. Initiate the BNPL loan transaction.
5. Authenticate the customer and obtain authorization for the loan.
6. Calculate and retrieve the payment plan.
7. Render payment plan details back to the user within the retailer’s e-commerce platform.
8. Update order status and fulfill the order by dispatching the equipment.

These steps may involve multiple APIs owned by different teams—such as an Eligibility API and a Loan API—each with its own endpoints. Traditionally, retailers would have to manually interpret multiple API documents and stitch together the calls themselves.

With Arazzo, the entire workflow is documented explicitly, providing retailers with a clear, machine-readable guide to integrating BNPL capabilities with minimal friction.

Enhancing Developer Experience with Tooling and Automation

While the Arazzo YAML document is powerful, the real magic happens when tooling is built on top of the specification. Instead of developers parsing raw YAML, tools can present workflows as:

• Interactive, living documentation that guides developers through each step.
• Diagrammatic representations using PlantUML or Mermaid to visualize workflows.
• Code snippets tailored to the specific use case and API calls involved.
• SDKs generated around workflows, avoiding unnecessary boilerplate code.

For example, a developer portal powered by Arazzo could display a BNPL integration guide that clearly shows the necessary API calls, expected inputs and outputs, and success criteria. This focused approach dramatically improves onboarding and reduces integration errors.

Leveraging AI for Arazzo Document Generation

How can AI assist in creating Arazzo documents? By feeding the AI information about the APIs and desired workflow steps, it can generate 80-90% accurate Arazzo YAML files, which developers can then refine.

Additionally, AI can generate documentation and diagrams from these files, accelerating the creation of developer-friendly materials.

The Emerging Ecosystem Around Arazzo

Since its formal launch, the Arazzo specification has gained support from various vendors, signaling a healthy and growing ecosystem:

• LibLab: SDK generation support.
• Redactly: Linting capabilities via the Redactly CLI, with a roadmap for enhanced Arazzo support.
• APImatic: Integration of Arazzo into guided walkthroughs for SDK generation.
• Speakeasy: Developing testing tools for Arazzo workflows.
• SmartBear and Stoplight: Spectral support for Arazzo, enabling governance and validation similar to OpenAPI and AsyncAPI.

For example, using Spectral, developers can lint Arazzo documents to ensure they conform to best practices and detect errors early in the development cycle. This automated validation can be integrated into CI/CD pipelines, boosting confidence in workflow correctness before deployment.

Validating and Improving Arazzo Documents

Linting tools have been used to identify and fix issues within example Arazzo documents in the official GitHub repository. This iterative process improves the quality and reliability of sample workflows, helping the community adopt best practices.

Such validation steps are crucial for maintaining the integrity of workflow descriptions, especially as they become central to API integration and automation.

Getting Started with Arazzo

For developers and API teams eager to explore Arazzo, here are some recommended steps:

1. Create Arazzo Documents: Begin by describing your API workflows in YAML or JSON using the Arazzo specification.
2. Use Linting Tools: Validate your documents with tools like Spectral or Redactly CLI to catch errors and enforce standards.
3. Join the Community: Engage with the OpenAPI Slack workspace, joining the dedicated Arazzo channel to share use cases and get support.
4. Contribute Feedback: Submit use cases, documentation improvements, and feature requests to the official repositories to shape the specification’s evolution.
5. Explore Tooling: Experiment with SDK generation, testing, and documentation tools that support Arazzo to streamline your API development lifecycle.

Conclusion: Why Arazzo is a Game-Changer for API Workflows

The Arazzo specification addresses a critical gap in the API ecosystem by providing a standardized, deterministic way to describe API workflows. It empowers developers, providers, and regulators alike to understand, validate, and automate complex API interactions that span multiple services.

By combining human-readable documentation with machine-readable precision, Arazzo enhances the developer experience, reduces integration friction, and enables better governance and testing.

As the ecosystem around Arazzo matures—with growing vendor support, tooling innovations, and community contributions—it promises to become an indispensable part of modern API design and consumption.

Whether you are building complex business workflows, generating SDKs for specific use cases, or enabling AI-driven API consumption, Arazzo offers the clarity and structure needed to succeed in today’s API-driven world.

“We’re incredibly excited about the Arazzo specification. It could be the missing piece of the API puzzle.” – Frank Kilkomins

Start exploring Arazzo today and join the movement to transform how we document, consume, and govern APIs across the industry.