{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"document-workflows-for-multiple-apis-with-arazzo","__idx":0},"children":["Document workflows for multiple APIs with Arazzo"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-is-arazzo","__idx":1},"children":["What is Arazzo?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Arazzo is an OpenAPI specification designed specifically for expressing workflows and articulating functional use cases that span multiple APIs. For a more detailed introduction, see ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/arazzo/what-is-arazzo"},"children":["What is Arazzo?"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Let's step back from software for a moment and think about physical architecture. Imagine you're an architect looking at a set of blueprints. Traditional API documentation is like having detailed drawings of each individual room in a building — you can see exactly how the kitchen is laid out, the dimensions of the bathroom, or where each electrical outlet is placed."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"graph TD\n A[Traditional API Docs] --> B[Individual Endpoints]\n C[Arazzo] --> D[Connected Workflows]\n B --> E[Isolated Rooms]\n D --> F[Complete Building]\n","diagramHtml":"

Traditional API Docs

Individual Endpoints

Arazzo

Connected Workflows

Isolated Rooms

Complete Building

","diagramHtmlDark":"

Traditional API Docs

Individual Endpoints

Arazzo

Connected Workflows

Isolated Rooms

Complete Building

"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["But what if you want to understand how people actually ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["move"]}," through these spaces? How do they navigate from the front door to the kitchen, then to the dining room for a meal? These movement patterns and workflows are equally important to the building's function, yet they're missing from individual room blueprints."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Arazzo fills this gap in the API ecosystem. Just as OpenAPI revolutionized how we document HTTP endpoints, Arazzo provides a standardized, machine-readable way to document complex multi-step workflows that involve multiple API calls."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Arazzo specification enables you to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Document complex, multi-step workflows in a format that's both human and machine-readable"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Increase internal knowledge of how APIs are used together"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create better understanding of dependencies, data flow, and business logic across APIs"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test complete user journeys rather than just individual API calls"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["But, why does this matter? Good Question! By documenting complete API workflows that accomplish real business outcomes, Arazzo bridges the gap between technical implementation and business requirements. Product managers gain insight into how features actually work across systems, developers understand the broader impact of their code changes, and QA teams can validate that full user journeys—not just individual endpoints—deliver the promised experience, creating alignment that drives more successful (and likely faster and less error prone) product development."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Arazzo emerged from a working group formed in 2021 under the OpenAPI Initiative. Since then, it has grown from a concept into a full specification!"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["At Redocly, we view Arazzo as a game-changing development for API producers. As our CEO Adam Altman shared in our ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/blog/arazzo-roadmap"},"children":["Arazzo roadmap blog post"]},", this approach mirrors how we've been thinking about APIs for years. Our internal product Respect (which we've made available for use) has been using a similar philosophy to test API workflows rather than just endpoints. When we discovered the Arazzo project, we recognized an opportunity to contribute to a standardized approach for workflow documentation that would benefit the entire API ecosystem."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-to-use-arazzo","__idx":2},"children":["Why to use Arazzo"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Continuing our architectural metaphor, consider what happens when a client commissions a building. They don't just want to know what each room looks like in isolation—they want to understand how the entire structure functions as a cohesive whole. How does foot traffic flow during a busy event? Where are the bottlenecks? How do service staff navigate from kitchen to dining areas efficiently? Learn more about ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/arazzo/why-arazzo-matters"},"children":["Why Arazzo Matters"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Arazzo addresses this fundamental gap by providing a standardized way to document workflows that use multiple APIs to achieve an outcome or complete a task. Until now, API producers have been like architects handing over individual room designs without circulation diagrams:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Using separate tools like Postman Collections to demonstrate workflow sequences (more like hand-drawn maps rather than professional circulation diagrams)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Creating external documentation and guides that quickly become outdated (similar to having the building's usage patterns documented separately from the blueprints)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Employing non-standardized approaches that aren't consistent with how people browse OpenAPI documentation (like using different scales and formats for different aspects of the building plans)"]}]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"mindmap\n root((API))\n Traditional\n Individual Endpoints\n Static Documentation\n Isolated Components\n Arazzo\n Connected Workflows\n Dynamic Documentation\n Integrated Systems\n","diagramHtml":"

API

Traditional

Individual Endpoints

Static Documentation

Isolated Components

Arazzo

Connected Workflows

Dynamic Documentation

Integrated Systems

","diagramHtmlDark":"

API

Traditional

Individual Endpoints

Static Documentation

Isolated Components

Arazzo

Connected Workflows

Dynamic Documentation

Integrated Systems

"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["What's particularly problematic about these approaches is that they often live outside the core API documentation, creating potential disconnects between documented functionality and actual implementation. When APIs change, these external workflow documents frequently get left behind—just as revised blueprints might not get reflected in separate circulation diagrams."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By integrating workflow documentation directly alongside your OpenAPI specs, Arazzo helps:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Improve internal and external API consumer experience (like providing both detailed room layouts AND circulation patterns in the same document set)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Increase understanding of what's possible with your APIs (showing not just what rooms exist, but how they're meant to be used together)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Support enablement, testing, and monitoring activities (ensuring the building works as designed in real-world usage)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["At Redocly, we've embraced this approach because it directly addresses two critical issues:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["It reduces the potential for mismatch between documentation and implementation (ensuring the actual building matches ALL aspects of the design)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["It ensures APIs are practical, runnable, testable, and monitorable from end to end (confirming people can actually move through the spaces as intended)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-your-apis-benefit-from-arazzo","__idx":3},"children":["How your APIs benefit from Arazzo"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In architecture, there's a world of difference between a building that looks good on paper and one that functions well in reality. Similarly, Arazzo transforms your API documentation from static blueprints into a living, functional guide."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We believe Arazzo matters because it fundamentally changes how API producers think about their offerings. Before shipping an API, Arazzo documentation forces you to explain how the API will be used in practical, real-world scenarios. This shifts the paradigm from documenting endpoints to documenting outcomes."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart LR\n A[API Producer] --> B[Documentation]\n B --> C[Consumer Understanding]\n C --> D[Successful Integration]\n","diagramHtml":"

API Producer

Documentation

Consumer Understanding

Successful Integration

","diagramHtmlDark":"

API Producer

Documentation

Consumer Understanding

Successful Integration

"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Too often, well-intentioned API producers create excellent APIs but leave the burden of figuring out practical applications entirely to consumers. While internal teams might have unit tests for individual endpoints, that's fundamentally different from describing sequences of API calls across multiple services that achieve practical business outcomes — like testing that a door works versus confirming that the entire fire evacuation route functions as designed."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"external-api-benefits","__idx":4},"children":["External API benefits"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For external APIs, Arazzo is providing a guided tour instead of just handing over the blueprints and wishing visitors good luck."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Arazzo encourages more effective human integrations by:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Replacing expensive alternatives for explaining API workflows:"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Traditional guides and tutorials are high-cost to create, difficult to verify, and become outdated quickly"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Without clear workflow documentation, developers often abandon APIs that don't immediately work for their use case"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It also opens the door for more effective machine integrations, particularly for AI agents. As AI becomes more prevalent in development workflows, machine-readable documentation of what your API can accomplish (not just what endpoints exist) will become increasingly valuable."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"workflows:\n - workflowId: createAndUpdateUser\n summary: Create a user and update their profile\n description: Shows how to create a user and then update their profile information\n steps:\n - stepId: createUser\n description: Create a user with basic information\n operationPath: '{$sourceDescriptions.users.url}#/paths/~1users/post'\n requestBody:\n payload:\n email: \"john.doe@example.com\"\n name: \"John Doe\"\n successCriteria:\n - condition: $statusCode == 201\n outputs:\n userId: $response.body#/id\n - stepId: updateProfile\n description: Add additional profile information\n operationPath: '{$sourceDescriptions.users.url}#/paths/~1users~1{userId}/patch'\n parameters:\n - name: userId\n in: path\n value: $steps.createUser.outputs.userId\n requestBody:\n payload:\n address: \"123 Main St\"\n phoneNumber: \"555-123-4567\"\n successCriteria:\n - condition: $statusCode == 200\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"internal-api-benefits","__idx":5},"children":["Internal API benefits"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For internal APIs, Arazzo serves as both blueprint and building inspector for your API ecosystem—ensuring not just that individual rooms are built to code, but that the entire structure functions as designed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An API can comply with all technical requirements and still not be practical in real-world scenarios. Arazzo documentation forces producers to use their APIs practically, revealing gaps in functionality that might otherwise remain hidden until consumers encounter them."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Internal benefits include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensuring APIs work together to support actual business processes (like confirming all evacuation routes are functional)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Documenting dependencies between services that might not be obvious from individual API specs (like showing how HVAC, electrical, and plumbing systems interact)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Providing clear examples for internal teams transitioning to new API versions or features (like updating staff on the new layout after a renovation)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-arazzo-works","__idx":6},"children":["How Arazzo works"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"arazzo-descriptions","__idx":7},"children":["Arazzo descriptions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Arazzo descriptions function like the circulation diagrams in an architectural plan. While the detailed room blueprints (OpenAPI specs) remain unchanged, Arazzo adds the critical layer that shows how people move through and use these spaces together. For a deeper understanding of workflows and steps, see ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/arazzo/understanding-workflows-and-steps"},"children":["Understanding Workflows and Steps"]},"."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart LR\n Title[\"Workflow Step Relationships and Data Flow\"]:::title\n A[Step 1] -->|Outputs| B[Step 2]\n B -->|Outputs| C[Step 3]\n A -->|Variables| D[Success Criteria]\n B -->|Variables| E[Success Criteria]\n C -->|Variables| F[Success Criteria]\n\n classDef title fill:#fff,stroke:#fff,color:#000,font-weight:bold\n","diagramHtml":"

Outputs

Outputs

Variables

Variables

Variables

Workflow Step Relationships and Data Flow

Step 1

Step 2

Step 3

Success Criteria

Success Criteria

Success Criteria

","diagramHtmlDark":"

Outputs

Outputs

Variables

Variables

Variables

Workflow Step Relationships and Data Flow

Step 1

Step 2

Step 3

Success Criteria

Success Criteria

Success Criteria

"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These descriptions are separate documents that reference your existing OpenAPI descriptions. This approach allows you to leave your OpenAPI documentation as is while augmenting it with workflow documentation. Typically, Arazzo files are stored alongside OpenAPI specs in your repository, making them part of the same versioning and review processes — just as circulation diagrams would be filed alongside the detailed room drawings in an architect's office."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '16px'}}}%%\n%% title: Basic Arazzo File Structure\ngraph TD\n A[Arazzo File] --> B[Info]\n A --> C[Source Descriptions]\n A --> D[Workflows]\n B --> B1[Title]\n B --> B2[Version]\n B --> B3[Description]\n C --> C1[OpenAPI Specs]\n D --> D1[Steps]\n D --> D2[Step Success Criteria]\n D --> D3[Outputs]\n","diagramHtml":"

Arazzo File

Info

Source Descriptions

Workflows

Title

Version

Description

OpenAPI Specs

Steps

Step Success Criteria

Outputs

","diagramHtmlDark":"

Arazzo File

Info

Source Descriptions

Workflows

Title

Version

Description

OpenAPI Specs

Steps

Step Success Criteria

Outputs

"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's a comprehensive example of an Arazzo structure that demonstrates real-world API workflow documentation:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"arazzo: 1.0.1\ninfo:\n title: Healthcare Patient Onboarding\n version: 1.0.0\n description: |\n Complete patient onboarding workflow that spans multiple healthcare systems.\n This workflow demonstrates error handling, conditional paths, and data flow\n between different healthcare services.\n\nsourceDescriptions:\n - name: patient-registry\n type: openapi\n url: ./patient-registry-api.yaml\n - name: insurance-verification\n type: openapi\n url: ./insurance-api.yaml\n - name: appointment-scheduling\n type: openapi\n url: ./scheduling-api.yaml\n\ncomponents:\n parameters:\n authorizationHeader:\n name: Authorization\n in: header\n required: true\n failureActions:\n standardRetry:\n name: standardRetry\n type: retry\n retryLimit: 3\n retryAfter: 1\n successActions:\n continueToNext:\n name: continueToNext\n type: goto\n stepId: next\n gotoScheduleAppointment:\n name: gotoScheduleAppointment\n type: goto\n stepId: scheduleAppointment\n gotoHandleUnverified:\n name: gotoHandleUnverified\n type: goto\n workflowId: handleUnverified\n\nworkflows:\n - workflowId: patientOnboarding\n summary: New Patient Registration and Scheduling\n description: |\n Complete workflow for registering a new patient, verifying insurance,\n and scheduling their first appointment. Includes error handling and\n conditional paths based on insurance verification results.\n inputs:\n type: object\n properties:\n firstName:\n type: string\n lastName:\n type: string\n dateOfBirth:\n type: string\n format: date\n insuranceProvider:\n type: string\n insuranceId:\n type: string\n preferredAppointmentDate:\n type: string\n format: date\n failureActions:\n - name: handleCriticalFailure\n type: goto\n workflowId: handleUnverified\n criteria:\n - condition: $statusCode >= 500\n\n steps:\n - stepId: registerPatient\n description: Create new patient record in the system\n operationPath: '{$sourceDescriptions.patient-registry.url}#/paths/~1patients/post'\n parameters:\n - $components.parameters.authorizationHeader\n requestBody:\n payload:\n firstName: {$inputs.firstName}\n lastName: {$inputs.lastName}\n dateOfBirth: {$inputs.dateOfBirth}\n successCriteria:\n - condition: $statusCode == 201\n outputs:\n patientId: $response.body#/id\n onFailure:\n - $components.failureActions.standardRetry\n onSuccess:\n - $components.successActions.continueToNext\n\n - stepId: verifyInsurance\n description: Verify patient's insurance coverage\n operationPath: '{$sourceDescriptions.insurance-verification.url}#/paths/~1verify/post'\n parameters:\n - $components.parameters.authorizationHeader\n requestBody:\n payload:\n patientId: {$steps.registerPatient.outputs.patientId}\n provider: {$inputs.insuranceProvider}\n insuranceId: {$inputs.insuranceId}\n successCriteria:\n - condition: $statusCode == 200\n - context: $response.body\n condition: $.status\n type: jsonpath\n outputs:\n coverageDetails: $response.body#/coverage\n isVerified: $response.body#/status\n onSuccess:\n - $components.successActions.gotoScheduleAppointment\n criteria:\n - condition: $response.body.status == \"verified\"\n - $components.successActions.gotoHandleUnverified\n criteria:\n - condition: $response.body.status != \"verified\"\n\n - stepId: scheduleAppointment\n description: Schedule initial appointment\n operationPath: '{$sourceDescriptions.appointment-scheduling.url}#/paths/~1appointments/post'\n parameters:\n - $components.parameters.authorizationHeader\n requestBody:\n payload:\n patientId: {$steps.registerPatient.outputs.patientId}\n preferredDate: {$inputs.preferredAppointmentDate}\n appointmentType: \"initial_consultation\"\n insuranceDetails: {$steps.verifyInsurance.outputs.coverageDetails}\n successCriteria:\n - condition: $statusCode == 201\n outputs:\n appointmentId: $response.body#/id\n appointmentDate: $response.body#/scheduledDate\n onSuccess:\n - $components.successActions.continueToNext\n\n - stepId: sendWelcomeEmail\n description: Send welcome email with appointment details\n operationPath: '{$sourceDescriptions.patient-registry.url}#/paths/~1notifications~1email/post'\n parameters:\n - $components.parameters.authorizationHeader\n requestBody:\n payload:\n patientId: {$steps.registerPatient.outputs.patientId}\n template: \"welcome\"\n data:\n appointmentId: {$steps.scheduleAppointment.outputs.appointmentId}\n appointmentDate: {$steps.scheduleAppointment.outputs.appointmentDate}\n insuranceStatus: {$steps.verifyInsurance.outputs.isVerified}\n successCriteria:\n - condition: $statusCode == 200\n\n - workflowId: handleUnverified\n summary: Handle Unverified Insurance Cases\n description: Manages cases where insurance verification fails\n steps:\n - stepId: notifyUnverified\n description: Send notification about unverified insurance\n operationPath: '{$sourceDescriptions.patient-registry.url}#/paths/~1notifications~1email/post'\n parameters:\n - $components.parameters.authorizationHeader\n requestBody:\n payload:\n patientId: {$steps.registerPatient.outputs.patientId}\n template: \"insurance_unverified\"\n data:\n provider: {$inputs.insuranceProvider}\n insuranceId: {$inputs.insuranceId}\n successCriteria:\n - condition: $statusCode == 200\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This example demonstrates several advanced Arazzo features:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Workflow Inputs"]},": Defines structured input parameters with JSON Schema validation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Error Handling"]},": Implements retry logic using reusable failure actions from components"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Flow Control"]},": Uses reusable success actions for both sequential and conditional branching"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Data Flow"]},": Shows how data flows between steps using outputs and inputs"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Success Criteria"]},": Uses proper JSONPath expressions for response validation at the step level"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Reusable Components"]},": Defines and references common parameters and actions using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$components"]}," expressions"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Workflow-level Actions"]},": Demonstrates workflow-level failure actions"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Multi-Service Integration"]},": Spans multiple healthcare systems (patient registry, insurance, scheduling)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Business Logic"]},": Implements real-world healthcare workflow patterns"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Best practices for Arazzo descriptions include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Focus on real-world use cases that consumers might need to implement (like documenting common visitor journeys through a building)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include all necessary steps in the workflow, from authentication to final outcome (showing the complete path from entrance to destination)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Extract and reuse values (like IDs or tokens) between steps (accounting for how one action affects subsequent ones)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Document expected responses at each stage to enable effective testing (like noting what should happen at each point in the journey)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use reusable components to maintain consistency and reduce duplication across workflows"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Define success criteria at the step level, not the workflow level, as per the Arazzo Specification"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Name all reusable objects in the components section as required by the specification"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Apply criteria to component references when needed for conditional execution"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"arazzo-linting","__idx":8},"children":["Arazzo linting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In architecture, building inspectors ensure that designs meet code requirements before construction begins. Similarly, Arazzo linting ensures your workflow documentation remains accurate and follows best practices before it reaches your API consumers. Learn more about ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/arazzo/linting-arazzo-workflows"},"children":["Linting Arazzo Workflows"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Redocly CLI provides linting capabilities for Arazzo files, helping you:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Validate that referenced OpenAPI operations actually exist (ensuring doors in your circulation diagrams actually exist in the room blueprints)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensure proper syntax and structure in your Arazzo documents (maintaining consistent notation and scale)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify that extracted variables are used correctly in subsequent steps (confirming logical progression between spaces)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Maintain consistency across your workflow documentation (keeping the same standards throughout your building plans)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"arazzo-use-cases-and-examples","__idx":9},"children":["Arazzo use cases and examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"technical-pattern-based-examples","__idx":10},"children":["Technical Pattern-Based Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"authentication-and-authorization","__idx":11},"children":["Authentication and Authorization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's an example of an OAuth2 flow with multiple providers:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"arazzo: 1.0.1\ninfo:\n title: Multi-Provider OAuth2 Flow\n version: 1.0.0\n description: Demonstrates OAuth2 authentication flow with multiple identity providers\n\nsourceDescriptions:\n - name: auth-service\n type: openapi\n url: ./auth-service.yaml\n - name: user-service\n type: openapi\n url: ./user-service.yaml\n\nworkflows:\n - workflowId: oauth2Authentication\n summary: OAuth2 Authentication with Multiple Providers\n description: Complete OAuth2 flow supporting multiple identity providers\n inputs:\n type: object\n properties:\n provider:\n type: string\n enum: [google, github, microsoft]\n redirectUri:\n type: string\n format: uri\n steps:\n - stepId: initiateAuth\n description: Start OAuth2 flow with selected provider\n operationPath: '{$sourceDescriptions.auth-service.url}#/paths/~1oauth2~1{provider}~1authorize/get'\n parameters:\n - name: provider\n in: path\n value: {$inputs.provider}\n - name: redirect_uri\n in: query\n value: {$inputs.redirectUri}\n successCriteria:\n - condition: $statusCode == 302\n outputs:\n authUrl: $response.headers#/location\n\n - stepId: handleCallback\n description: Process OAuth2 callback and exchange code for tokens\n operationPath: '{$sourceDescriptions.auth-service.url}#/paths/~1oauth2~1{provider}~1token/post'\n parameters:\n - name: provider\n in: path\n value: {$inputs.provider}\n requestBody:\n payload:\n code: {$inputs.code}\n redirect_uri: {$inputs.redirectUri}\n successCriteria:\n - condition: $statusCode == 200\n outputs:\n accessToken: $response.body#/access_token\n refreshToken: $response.body#/refresh_token\n\n - stepId: getUserProfile\n description: Fetch user profile using obtained access token\n operationPath: '{$sourceDescriptions.user-service.url}#/paths/~1me/get'\n parameters:\n - name: Authorization\n in: header\n value: \"Bearer {$steps.handleCallback.outputs.accessToken}\"\n successCriteria:\n - condition: $statusCode == 200\n outputs:\n userId: $response.body#/id\n email: $response.body#/email\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"data-synchronization","__idx":12},"children":["Data Synchronization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of a real-time data replication workflow:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"arazzo: 1.0.1\ninfo:\n title: Real-time Data Replication\n version: 1.0.0\n description: Demonstrates real-time data synchronization between systems\n\nsourceDescriptions:\n - name: source-db\n type: openapi\n url: ./source-db-api.yaml\n - name: target-db\n type: openapi\n url: ./target-db-api.yaml\n\nworkflows:\n - workflowId: dataReplication\n summary: Real-time Data Replication Workflow\n description: Replicates data changes from source to target system\n steps:\n - stepId: captureChanges\n description: Capture changes from source system\n operationPath: '{$sourceDescriptions.source-db.url}#/paths/~1changes/get'\n parameters:\n - name: since\n in: query\n value: {$inputs.lastSyncTimestamp}\n successCriteria:\n - condition: $statusCode == 200\n outputs:\n changes: $response.body#/changes\n newTimestamp: $response.body#/timestamp\n\n - stepId: applyChanges\n description: Apply changes to target system\n operationPath: '{$sourceDescriptions.target-db.url}#/paths/~1sync/post'\n requestBody:\n payload:\n changes: {$steps.captureChanges.outputs.changes}\n successCriteria:\n - condition: $statusCode == 200\n onFailure:\n - name: retryOnConflict\n type: retry\n criteria:\n - condition: $statusCode == 409\n retryLimit: 3\n retryAfter: 1\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"business-process-focused-examples","__idx":13},"children":["Business Process-Focused Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"customer-journey-workflows","__idx":14},"children":["Customer Journey Workflows"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of a subscription management workflow:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"arazzo: 1.0.1\ninfo:\n title: Subscription Management\n version: 1.0.0\n description: Complete subscription lifecycle management workflow\n\nsourceDescriptions:\n - name: subscription-service\n type: openapi\n url: ./subscription-api.yaml\n - name: billing-service\n type: openapi\n url: ./billing-api.yaml\n - name: notification-service\n type: openapi\n url: ./notification-api.yaml\n\nworkflows:\n - workflowId: subscriptionLifecycle\n summary: Subscription Lifecycle Management\n description: Handles the complete lifecycle of a subscription\n inputs:\n type: object\n properties:\n customerId:\n type: string\n planId:\n type: string\n paymentMethodId:\n type: string\n steps:\n - stepId: createSubscription\n description: Create new subscription\n operationPath: '{$sourceDescriptions.subscription-service.url}#/paths/~1subscriptions/post'\n requestBody:\n payload:\n customerId: {$inputs.customerId}\n planId: {$inputs.planId}\n paymentMethodId: {$inputs.paymentMethodId}\n successCriteria:\n - condition: $statusCode == 201\n outputs:\n subscriptionId: $response.body#/id\n onSuccess:\n - type: goto\n stepId: processInitialPayment\n\n - stepId: processInitialPayment\n description: Process initial subscription payment\n operationPath: '{$sourceDescriptions.billing-service.url}#/paths/~1payments/post'\n requestBody:\n payload:\n subscriptionId: {$steps.createSubscription.outputs.subscriptionId}\n amount: {$response.body#/amount}\n successCriteria:\n - condition: $statusCode == 200\n onFailure:\n - name: handlePaymentFailure\n type: goto\n workflowId: handleFailedPayment\n criteria:\n - condition: $statusCode == 402\n onSuccess:\n - type: goto\n stepId: sendWelcomeEmail\n\n - stepId: sendWelcomeEmail\n description: Send welcome email to new subscriber\n operationPath: '{$sourceDescriptions.notification-service.url}#/paths/~1notifications~1email/post'\n requestBody:\n payload:\n template: \"subscription_welcome\"\n data:\n subscriptionId: {$steps.createSubscription.outputs.subscriptionId}\n customerId: {$inputs.customerId}\n successCriteria:\n - condition: $statusCode == 200\n\n - workflowId: handleFailedPayment\n summary: Handle Failed Payment\n description: Manages cases where initial payment fails\n steps:\n - stepId: notifyPaymentFailure\n description: Send notification about failed payment\n operationPath: '{$sourceDescriptions.notification-service.url}#/paths/~1notifications~1email/post'\n requestBody:\n payload:\n template: \"payment_failed\"\n data:\n subscriptionId: {$steps.createSubscription.outputs.subscriptionId}\n customerId: {$inputs.customerId}\n successCriteria:\n - condition: $statusCode == 200\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"operational-workflows","__idx":15},"children":["Operational Workflows"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of a deployment workflow:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"arazzo: 1.0.1\ninfo:\n title: Service Deployment\n version: 1.0.0\n description: Automated service deployment workflow\n\nsourceDescriptions:\n - name: deployment-service\n type: openapi\n url: ./deployment-api.yaml\n - name: monitoring-service\n type: openapi\n url: ./monitoring-api.yaml\n\nworkflows:\n - workflowId: serviceDeployment\n summary: Service Deployment Workflow\n description: Handles the deployment of a new service version\n inputs:\n type: object\n properties:\n serviceName:\n type: string\n version:\n type: string\n environment:\n type: string\n enum: [staging, production]\n steps:\n - stepId: deployService\n description: Deploy new service version\n operationPath: '{$sourceDescriptions.deployment-service.url}#/paths/~1deploy/post'\n requestBody:\n payload:\n serviceName: {$inputs.serviceName}\n version: {$inputs.version}\n environment: {$inputs.environment}\n successCriteria:\n - condition: $statusCode == 200\n outputs:\n deploymentId: $response.body#/id\n onSuccess:\n - type: goto\n stepId: verifyDeployment\n\n - stepId: verifyDeployment\n description: Verify deployment health\n operationPath: '{$sourceDescriptions.monitoring-service.url}#/paths/~1health/get'\n parameters:\n - name: deploymentId\n in: query\n value: {$steps.deployService.outputs.deploymentId}\n successCriteria:\n - condition: $statusCode == 200\n - context: $response.body\n condition: $.status\n type: jsonpath\n onFailure:\n - name: rollbackDeployment\n type: goto\n workflowId: rollbackService\n criteria:\n - condition: $statusCode != 200\n\n - workflowId: rollbackService\n summary: Rollback Failed Deployment\n description: Handles rollback of failed deployments\n steps:\n - stepId: initiateRollback\n description: Start deployment rollback\n operationPath: '{$sourceDescriptions.deployment-service.url}#/paths/~1rollback/post'\n requestBody:\n payload:\n deploymentId: {$steps.deployService.outputs.deploymentId}\n successCriteria:\n - condition: $statusCode == 200\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These examples demonstrate how Arazzo can be used to document and implement both technical patterns and business processes. Each example includes:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Clear workflow structure and dependencies"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Error handling and recovery strategies"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Data flow between steps"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Input validation and output mapping"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Success criteria and failure handling"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Real-world implementation patterns"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"api-contract-testing","__idx":16},"children":["API contract testing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There's a vast difference between checking that individual components meet specifications (like testing that a door closes properly) and verifying that the entire building functions as designed. Arazzo enables this holistic testing approach for your APIs. For more details on testing, see ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/arazzo/testing-arazzo-workflows"},"children":["Testing Arazzo Workflows"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly's internal tool (Respect) has long emphasized the importance of testing API workflows rather than just individual API calls. With Arazzo, this approach becomes standardized and accessible to all API producers."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Contract testing with Arazzo allows you to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Validate that entire user journeys work as expected"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test interactions between multiple microservices or APIs"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensure that data flows correctly from one step to the next"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Detect breaking changes that might not be apparent from testing individual endpoints"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"end-to-end-api-testing","__idx":17},"children":["End-to-end API testing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["End-to-end testing with Arazzo goes beyond contract testing by validating complete user journeys in real-world scenarios. This approach is like conducting a full building simulation with actual users rather than just verifying plans meet code requirements."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With Arazzo-based end-to-end testing, you can:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Automate testing of entire workflows in CI/CD pipelines"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Validate business-critical journeys across multiple systems"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test with real or mocked dependencies"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create living documentation that proves your APIs work as described"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the latest updates on our Arazzo support, check out our ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/blog/arazzo-roadmap"},"children":["Arazzo roadmap blog post"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-started-with-arazzo","__idx":18},"children":["Get started with Arazzo"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ready to transform your API documentation from static blueprints to complete architectural plans with circulation patterns? Here's how to get started:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Learn from real examples"]},": Review the examples in this article, including the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#arazzo-descriptions"},"children":["Healthcare Patient Onboarding"]}," workflow and ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#technical-pattern-based-examples"},"children":["Technical Pattern-Based Examples"]}," sections above."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create your first workflow"]},": Start with a simple, common use case that involves multiple API calls. Check out ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/arazzo/arazzo-basics"},"children":["Arazzo Basics"]}," for a gentle introduction."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Validate your workflow"]},": Use the Redocly CLI to lint and validate your Arazzo files. Learn more about ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/arazzo/success-criteria-and-failure-handling"},"children":["Success Criteria and Failure Handling"]},":",{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"npx @redocly/cli@latest lint YOUR_ARAZZO_FILE\n","lang":"sh"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Integrate with your documentation"]},": Store your Arazzo files alongside your OpenAPI specs. See ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/arazzo/source-descriptions-and-refs"},"children":["Source Descriptions and References"]}," for best practices."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use Respect to run your workflows"]},": Execute your Arazzo workflows with Redocly CLI. For a complete walkthrough, see ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/arazzo/arazzo-walkthrough"},"children":["Arazzo Walkthrough"]},":",{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"npx @redocly/cli@latest respect YOUR_ARAZZO_FILE\n","lang":"sh"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As you begin implementing Arazzo, remember that the most valuable workflows are those that reflect real-world usage patterns. Focus on documenting the journeys that matter most to your API consumers. This approach will yield immediate benefits in terms of comprehension, integration success, and overall API usability."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Join us in embracing this new standard for API workflow documentation."]}]},"frontmatter":{},"tagList":[],"title":"Document workflows for multiple APIs with Arazzo","lastModified":"2025-06-27T16:42:31.000Z"}