In the rapidly evolving world of APIs, describing individual endpoints is no longer enough. While the OpenAPI Specification (OAS) has revolutionized how we document single APIs by providing a standardized, machine-readable format for HTTP interfaces, real-world API usage often involves complex sequences of calls across one or multiple APIs. This is where workflow standards like the Arazzo Specification come into play, bridging the gap between isolated endpoint descriptions and practical, outcome-driven interactions.
What is the Arazzo Specification?
Released in 2024 by the OpenAPI Initiative (with a patch update to version 1.0.1 in early 2025), Arazzo is a community-driven, language-agnostic standard designed to describe API workflows. Named after the Italian word for “tapestry,” it weaves together sequences of API calls, articulating dependencies, inputs, outputs, success criteria, and failure handling to achieve specific business outcomes.
Unlike OpenAPI, which focuses on defining paths, parameters, schemas, and responses for a single API, Arazzo operates at a higher level:
- It references one or more source descriptions (typically OpenAPI documents).
- It defines workflows as ordered steps, where outputs from one step (e.g., an authentication token) can feed into the next (e.g., a protected resource request).
- It supports reusable components, runtime expressions for dynamic values, and explicit success/failure actions.
An Arazzo document (in YAML or JSON) includes key elements like:
- Metadata (info object).
- Source descriptions (links to OpenAPI files).
- Workflows with inputs, steps, and criteria.
This makes workflows both human-readable for developers and machine-readable for tools.The Broader Role of Workflow Standards in APIsStandards like Arazzo address fundamental challenges in API consumption and production:
- Reducing Guesswork and Improving Developer Experience (DX)
Large APIs with hundreds of endpoints often overwhelm consumers. Documentation frequently becomes outdated or incomplete, leaving developers to reverse-engineer sequences through trial and error. Arazzo provides “recipes” for common use cases—e.g., user onboarding, payment processing, or pet adoption in the classic Petstore example—making onboarding faster and more reliable. - Enabling Automation and Tooling
Machine-readable workflows unlock powerful automation:- Targeted code generation (e.g., SDKs focused on specific flows rather than the entire API).
- Interactive documentation with executable examples.
- Automated testing and validation of end-to-end scenarios.
- Mocking and simulation for faster development cycles.
- Supporting Multi-API Orchestration
Modern applications rarely rely on a single API. Arazzo can describe interactions across multiple APIs, defining dependencies and data flows in ecosystems like open banking or microservices architectures. - Facilitating Compliance and Reliability
By defining explicit success/failure criteria, these standards support regulatory validation (e.g., assertable workflows for audits) and error handling, ensuring consistent behavior. - Preparing for the AI Era
One of the most exciting roles is enabling deterministic API consumption by AI agents. As large language models (LLMs) and autonomous agents become API consumers, vague prompts lead to hallucinations or errors. Arazzo provides structured, reliable workflows that AI can follow precisely—integrating with protocols like the Model Context Protocol (MCP) for agentic systems. This shifts API design from endpoint-focused to intent-focused, allowing agents to achieve business goals without unpredictable chaining.
Why Standards Like Arazzo Matter NowThe API landscape is exploding: organizations manage hundreds of endpoints, with AI agents emerging as new consumers. Without workflow standards, integration remains manual, error-prone, and slow. Arazzo complements OpenAPI (and related specs like Overlays for transformations), creating a more complete tapestry of API descriptions.By standardizing workflows, Arazzo and similar initiatives:
- Lower barriers to API adoption.
- Accelerate time-to-value for providers and consumers.
- Foster interoperability in an increasingly agent-driven world.
As tooling matures—linters, runners, visualizers, and AI integrations—Arazzo is poised to transform how we build, document, and consume APIs. In an era where undeployed APIs create no value, standards like this ensure APIs are not just described, but truly usable.
For those interested in exploring further, check the official Arazzo repository on GitHub or start experimenting with simple workflows alongside your existing OpenAPI documents. The future of APIs is not just about endpoints—it’s about orchestrated outcomes.