OpenAPI describes endpoints. Arazzo describes how to use them together
Describe dependencies, inputs and success conditions across API calls. Use Arazzo to make integration workflows explicit alongside OpenAPI.
Creating an order may require a customer ID, an inventory reservation and a payment reference. OpenAPI can describe all four operations. The integration also needs to explain which request runs first and where each later request gets its inputs.
Arazzo describes sequences of API calls and their dependencies. Keep that workflow document alongside the API descriptions and review changes to the sequence when an operation changes.
Start with a real integration path
Consider an illustrative purchase workflow: create a test customer, reserve an item, create an order using the returned identifiers, then retrieve the order to verify its state. OpenAPI describes each operation's request and response. The workflow explains how outputs from one step become inputs to another.
Name the workflow by the task a consumer is trying to complete. Define its external inputs and the source descriptions it references. Give steps stable identifiers and identify the operations or workflows they invoke using the supported specification constructs.
Keep environment-specific credentials outside the workflow document. A published workflow can describe the shape of the task without embedding secrets or granting permission to perform it. Execution still needs an environment, authorized credentials and a runner that supports the document.
Make success more precise than “returned 200”
A successful HTTP response may be necessary but insufficient. An order might exist in a pending state when the task requires confirmation. Arazzo provides success-condition and action constructs for expressing what should happen after a step.
Use those constructs to check the response fields that establish success. A reviewer should be able to follow each condition. If the business rule cannot be derived from the API description, explain it in the accompanying guide rather than hiding it in a complicated expression.
Describe failure branches as well as successful steps. A reservation might fail, an upstream request might time out, or a later step might reject an earlier reference. The workflow can describe actions; the executing application must implement their effects correctly.
A description is not an execution engine
An Arazzo document does not execute itself. Support depends on the tools consuming it, the version they implement and the constructs they support. Validate the document with the intended toolchain and exercise it against controlled fixtures.
Nor does a workflow create a transaction across independent services. If the third step fails after the first two succeed, cleanup or compensation requires explicit API capabilities and application logic. A description of “release reservation” cannot undo a real-world action that the API does not support reversing.
For asynchronous work, describe how the workflow observes completion and handles terminal failure. A submission response and a completed business result remain different events even when a workflow joins them.
Review workflows with the API contract
When an operation changes, check the workflows that depend on its inputs and outputs. Validate references and response assumptions, and keep representative execution tests where your runner supports them. A syntactically valid workflow can still describe an integration that no longer works.
Use prose for intent, tradeoffs and domain context. Use the workflow document for machine-readable dependencies and conditions. Those artifacts serve different readers and should agree about the same task.
