OpenAPI
5 potential use cases for Arazzo
Bill Doerrfeld
January 22, 2025 - 7 min read
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 , a new specification from the OpenAPI Initiative that can be used to describe an interconnected series of API calls and their dependencies. Announced in mid-2024 , Arazzo is on version 1.0.1 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 . 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 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 , making a process like refreshing an access token more transparent and repeatable.
For example, the OAI provides an example of using Arazzo to describe a Financial Grade API (FAPI) profile , 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 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. 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 for Arazzo specifications. The Arazzo Specification repository also includes use cases such as securing a loan at a buy now pay later (BNPL) platform, or applying coupons to a purchase .
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 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.