OpenAPI

5 potential use cases for Arazzo

Bill Doerrfeld

January 22, 2025

Digital interactions often involve sequences of API calls to achieve goals like user authentication, booking a flight, or ordering a product online. These multi-step workflows rely on passing parameters between various services, with each step dependent on the outcome of preceding API calls. Although API-based workflows are commonplace, they typically aren’t formally documented, hindering repeatability and developer experience.

Enter Arazzo (opens in a new tab), a new specification from the OpenAPI Initiative (opens in a new tab) that can be used to describe an interconnected series of API calls and their dependencies. Announced in mid-2024 (opens in a new tab), Arazzo is on version 1.0.1 (opens in a new tab) at the time of writing.

Italian for “tapestry,” Arazzo is aptly named since it can be used to weave together sequences of API calls to illustrate a specific business pattern. Although new on the scene, the API community is excited about the potential of using Arazzo to standardize deterministic workflows for various use cases.

There are countless examples of interlinked API sequences out there, and defining them could greatly boost API-driven development. From better articulating common customer flows to empowering quality engineers and optimizing AI agents, there is a fountain of possibilities for using Arazzo (opens in a new tab). Below, we’ll explore a handful of possible use cases and how they could benefit developer consumers and their end business objectives.

1. Making AI more deterministic

AI has become a household technology. Yet, large language models (LLMs) are still prone to inaccuracies and hallucinations. Plus, autonomously integrating with APIs and performing interconnected interactions still poses a challenge. This is in part due to a lack of repeatable machine-readable API-related semantics for LLMs.

Arazzo could be used to apply more deterministic API processes to AI agents. By ingesting OpenAPI specifications and Arazzo definitions, an AI could understand what operations are available and what workflows they should invoke to perform common actions. This could greatly empower AI agents with greater context, optimize their behaviors, and help reduce errors and randomness.

For example, consider an LLM-powered AI assistant within an online food ordering system. Suppose a user asks it to ‘re-order my last Thai dinner.’ An AI could invoke an Arazzo description related to reordering, detailing all the required steps, such as order look-ups, availability and balance checks, and payment processing, to set up and initiate a reorder.

2. Simplifying multi-endpoint libraries

Have you ever read an OpenAPI definition? The average API has 42 endpoints, and these YAML or JSON files can become pretty unwieldy, with thousands of lines and metadata that are often irrelevant to an individual use case. To make matters more complicated, many workflows call APIs from disparate sources, including internal and external services.

Arazzo could be used to greatly abstract complexity for developers by helping to document and generate workflows around common business functions. Rather than fully describing every endpoint and method in an API, Arazzo could help generate higher-level SDKs (opens in a new tab) that are multi-endpoint and use-case-specific.

For instance, consider a developer tooling company that offers recruiting software as a platform. Suppose a common functional use case is to recruit a candidate that matches certain criteria. Well, an Arazzo workflow could document how to search for a user, check they are free for work, initiate outreach in the system, and update the status to contacted. It could even automate external calls for background checks or pull in public social media information.

Arazzo could deterministically describe the API calls and parameters required to achieve this process. These libraries could even combine interactions across various APIs, greatly streamlining the developer experience.

3. Demystifying authorization flows

Modern applications don’t just authenticate the user — they make sure the user has the correct permissions. Behind the scenes, APIs typically require authorization flows using OpenID Connect and OAuth, involving back-and-forth exchanges between the requesting client, an API gateway, and an external identity server.

Arazzo could be used to formulate a sequence of calls for an OAuth service (opens in a new tab), making a process like refreshing an access token (opens in a new tab) more transparent and repeatable.

For example, the OAI provides an example of using Arazzo to describe a Financial Grade API (FAPI) profile (opens in a new tab), which is a common flow for PSD2 open banking scenarios. Defining this could streamline how developers implement financial security flows, removing some guesswork from the picture. That said, the authentication aspect of OAuth flows are often unspecified and will depend on the exact configurations of the identity server.

4. Automating end-to-end API testing

The standards for digital experiences are high, meaning quality assurance or site reliability engineers have their work cut out for them. API testing takes this to a whole new level since so much can go wrong with a programmatic interface that is continually updated and versioned. It takes a broad range of routine tests to ensure APIs are stable. From functional testing to performance testing, reliability testing, validation testing, security testing, chaos engineering, linting, and more.

QA engineers often create Postman Collections that save API calls, but wouldn’t it be nice to automate API testing? Arazzo could greatly aid end-to-end testing (opens in a new tab) to ensure sequences of API calls are fully functional and meet service-level agreements, bringing efficiency benefits to the testing process.

Consider engineers working within a healthcare company — these folks could use Arazzo workflows to automate regulatory compliance checks. For instance, a conformance testing workflow could test whether a system violates regulations around data sharing across regional boundaries when passed certain geographic-specific parameters.

5. Standardizing patterns in unified APIs

Unified APIs take the integration hassle out of aggregating tens, if not hundreds, of software systems and endpoints for similar domains. For instance, take Avage API for construction software, Argyle for payroll services, Duffel for airline booking, or Plaid for integrating with bank data. Many more unified APIs exist for categories like CRM, cloud storage, accounting, and more.

Unified APIs could greatly benefit from Arazzo since they already define common user experiences across software domains. There are many common, repeatable pathways within a particular domain. For instance, a unified CRM API could create an agnostic workflow for adding a new qualified lead to a CRM system. Actionable flows for standard processes like this could improve the unified API integration developer experience.

Optimizing working with Arazzo

It’s good to note that Arazzo’s actual utility will hinge on whether the API tooling ecosystem embraces it. Part of this will be making working with Arazzo more streamlined. Similar to API definition linting tools, the same thing for Arazzo is emerging, enabling you to validate that the Arazzo specification is correct. Speakeasy has open-sourced one such parser for this very purpose, speakeasy lint arazzo (opens in a new tab). Such tools will help API providers and API management platforms integrate Arazzo more easily into their pipelines and offerings.

Let’s see what the builders build

By defining common workflows, Arazzo could greatly reduce the mean time for integrations and help standardize complex descriptions typically housed in PDFs or Word documents outside of official API documentation. For developers, it can generate useful onboarding information to create more interactive, “living” workflow documentation.

Beyond the examples above, there are countless other potential use cases (opens in a new tab) for Arazzo specifications. The Arazzo Specification repository also includes use cases such as securing a loan at a buy now pay later (opens in a new tab) (BNPL) platform, or applying coupons to a purchase (opens in a new tab).

Arazzo is the first of its kind — a standard with growing industry momentum to denote composite API workflows around specific business goals. From an end consumer perspective, the standard could usher in more predictable AI agents (opens in a new tab) and better cross-platform customer experiences. For developers, Arazzo could streamline stitching together common request patterns, demystify security flows, and make testing easier.

A lot is hypothetical now, but the future is looking bright for this new standard. Now, it’s just up to the builders to build.