Arazzo Specification: A Practical Guide to API Design Workflows

The Arazzo specification is an OpenAPI Initiative standard that describes API workflows — ordered steps that call one or more APIs to achieve a goal. While a single OpenAPI specification focuses on a single API surface (paths, operations, schemas, security), an Arazzo description captures the choreography around those APIs: the inputs each step needs, the dependencies between steps, the success criteria that mark progress, and the outputs to pass forward. In short, Arazzo is a formal, machine‑readable way to model “do this, then that” scenarios that developers already build in code and testers already automate in suites.

In practice, most teams already deal with workflows:

• Sign in, then fetch profile, then update preferences
• Create cart, add items, compute totals, pay, and confirm
• Submit application, poll status, upload documents, receive approval

Arazzo gives these sequences a shared language. The format is JSON or YAML. A top‑level object declares the Arazzo version (arazzo: 1.0.x), metadata (info), a list of source API descriptions (sourceDescriptions, often OpenAPI specification files you already maintain), a list of workflows (workflows), and reusable pieces in components. Each workflow contains inputs (names and types), ordered steps (with step IDs), optional parameters injected into the referenced API calls, successCriteria (simple assertions such as $statusCode == 200), and outputs that later steps may consume.

Why does this matter for API design and API specification?

• It reduces guesswork. You show how the API is meant to be used, not only what each endpoint does in isolation.
• It improves hand‑offs. Product, backend, frontend, and QA read the same, short description of the workflow.
• It enables tools. Because Arazzo is machine‑readable, editors, linters, mockers, and runners can use it.
• It supports change. If an endpoint evolves, the workflow keeps consumers aligned on the happy path.

Arazzo does not replace the OpenAPI specification. Rather, it adds a layer on top. Arazzo points to one or more OpenAPI documents (via sourceDescriptions) and composes them into end‑to‑end flows. Keeping these roles distinct helps you stay clear: OpenAPI describes the API; Arazzo describes how to use one or more APIs to accomplish work.

Inside the Arazzo Specification Object

A quick guided tour helps you read and author Arazzo files with confidence. The main sections you will see are:

• arazzo: Arazzo version, for example 1.0.1.
• info: title, summary, description, and version of the workflow description.
• sourceDescriptions: a list of source specs used in workflows. Each entry has name, type (e.g., openapi), and a url to the source, such as a published OpenAPI specification.
• workflows: an array of workflow objects. Each contains workflowId, summary, description, inputs, steps, and workflow‑level outputs.
• components: reusable schemas used in the workflow description.

A typical step contains:

• stepId: a unique label, like loginStep or getPetStep.
• A reference to an API operation by operationId or operationPath that points into a source OpenAPI specification.
• parameters: values injected into the request, often taken from prior inputs or step outputs.
• successCriteria: simple boolean checks such as $statusCode == 200.
• outputs: variables captured from headers or body, e.g., tokenExpires: $response.header.X-Expires-After or sessionToken: $response.body.

To make the division of labor clear, use the following mental model:

How Arazzo Specification Complements the OpenAPI Specification

Arazzo and OpenAPI align well in API design. OpenAPI remains your contract of record for a service. Arazzo becomes your playbook for how to string services together. When you publish both, consumers understand the why and the how:

• Why each endpoint exists in the context of a business journey
• How to call them in order, what to pass, and what to expect back

Good practice:

• Keep sourceDescriptions pointing to stable, versioned OpenAPI specification URLs
• Name workflowId and stepId clearly; treat them like code you will search later
• Keep assertions simple and obvious; use them as living acceptance criteria
• Only capture outputs you will use. Shorter is easier to maintain

Examples That Ground the Arazzo Specification in Real API Design Scenarios

Let us anchor the idea with three common flows. We will keep it simple and avoid giant payloads, yet still show the value of Arazzo.

1. User login + list available items

• Inputs: username, password
• Steps: loginUser (success when $statusCode == 200), then getItems with a query status=available and header Authorization: $steps.loginUser.outputs.sessionToken
• Outputs: availableItems from $response.body

2. Checkout and payment capture

• Inputs: cartId, paymentMethod
• Steps: getCartTotals → createPaymentIntent → confirmPayment
• Pass along totals and a client secret between steps
• Assertions at each step ($statusCode == 200 and a field check such as $.status == "confirmed")

3. Application submission and polling

• Inputs: appPayload
• Steps: submitApplication → pollStatus repeats until $.state in ["APPROVED","REJECTED"]
• Outputs: decision and reason

In an Arazzo description, these read like a short script. Engineers, QA, technical writers, and partners can all scan them quickly. A few practical pointers when you author examples:

• Prefer operationId when you control the OpenAPI specification; it is stable under path changes
• Use operationPath when you must pinpoint a specific path in a third‑party OpenAPI
• Keep inputs typed and documented (string, number, object) to drive better forms and UI later
• Collect only outputs you need; avoid turning the workflow into a second data model
• Add a one‑line summary for each step as if you were writing a commit message

How this helps API design and API specification work together:

• API designers think in journeys and edge cases; Arazzo captures those in clear steps
• Developers gain a ready‑made acceptance checklist; it reduces back‑and‑forth
• Testers derive scenario tests straight from the workflow; no reinterpretation

Finally, because Arazzo is machine‑readable, you can build small utilities to render workflows into human docs, CI checks, or diagrams, and you can keep them close to your OpenAPI specification repository.

Using Apidog to Operationalize API Design: OpenAPI Specification + Arazzo‑aligned Workflows

Arazzo explains the workflow. OpenAPI explains the API. Apidog helps you turn both into a working product with less toil. While Arazzo is not an authoring format inside Apidog today, the platform maps naturally to its ideas and gives you the day‑to‑day tools to design, test, and publish APIs consumers trust.

Design and model with confidence:

• Visual API design for paths, operations, schemas, security, and examples
• Batch management for endpoints, global parameters, and reusable components
• Built‑in AI assistance and an AI‑powered endpoint compliance check to score documentation quality against your team's API design guidelines

Develop and debug faster:

• Rich request runner with environments, variables, and history
• Endpoint cases (scenario tests) that mirror step‑based flows: extract variables (JSONPath), chain requests, and assert success
• Data‑driven and performance tests to catch regressions early

Publish documentation that people and AIs can use:

• Live, interactive documentation that stays in sync with your OpenAPI specification
• Five access modes: Public, Password, IP allowlist, Email allowlist, and Custom Login
• LLM‑friendly features: publish Markdown for every page, generate llms.txt, enable MCP to guide IDE agents like Cursor or Cline

Distribute and learn:

• Publish public APIs to API Hub for discovery
• Use analytics and feedback loops to refine examples, descriptions, and test coverage

Arazzo gives you clear workflows. Apidog gives you the platform to shape, prove, and present your API around those workflows. The result is better API design, stronger API specification, and faster adoption.

Conclusion

The Arazzo specification adds missing context to API programs: it documents real workflows in a concise, machine‑readable way. Teams do not have to guess the call order, the inputs, or the success signals. Pair that with the OpenAPI specification, and you now own both the contract and the playbook. Stakeholders understand intent, and tools can automate the path from idea to working software.

To turn those documents into dependable software, adopt a platform that operationalizes good API design habits. Apidog provides a unified workspace to model endpoints, reuse components, run scenario tests, and publish documentation with strong access control and LLM‑friendly outputs. Features like the AI‑powered endpoint compliance check, endpoint cases, and publish‑time options (Markdown pages, llms.txt, MCP) help your API stay consistent, clear, and easy to integrate.

If you already manage an OpenAPI specification, consider adding an Arazzo description alongside it to capture your most important flows. Then import the spec into Apidog, build tests that mirror the workflow steps, and publish docs that help both people and AI assistants succeed. This combination reduces rework, speeds delivery, and raises confidence across your API lifecycle — from API design to API specification to adoption. Ready to go further? Sign up for Apidog and give your team the tools to deliver great APIs with less friction.