Arazzo

The gap Arazzo fills#

An OpenAPI document tells you every call you may make and none of the order in which they are useful. The knowledge that you must search before you fetch, or check status before you make a claim, normally lives in prose that a person reads and a program cannot. Arazzo moves that knowledge into a file.

A document names its sourceDescriptions — the OpenAPI documents it draws operations from — and then a list of workflows. Each workflow has inputs, ordered steps and outputs. Each step names an operation, supplies parameters, declares successCriteria that decide whether it worked, and exposes outputs that later steps refer to by name.

The result is a sequence a client can follow without a human having translated a tutorial into code, and — more usefully — one that can be tested. A step whose success criterion stops holding is a broken workflow, visible in a build rather than in a support ticket.

Does Connect use Arazzo?#

Yes, as a publisher. /developers/workflows.arazzo.yaml is generated by the documentation build to 1.1.0, drawing its operations from the public OpenAPI description. Three workflows are published, all over the public documentation API.

Nothing in Connect *executes* Arazzo. The file is a description for other people's tools; the product's own internal flows — a message arriving, a draft being approved, a call being placed — are not exposed as a developer API and do not appear here. Those are documented in prose under End-to-end workflows.

Reading a workflow file without learning the whole format#

1. Find sourceDescriptions at the top.

   Result You know which API the operations belong to — here, the public documentation API described by openapi.yaml.

2. Pick a workflow and read its summary and inputs.

   Result You know what it achieves and what you must supply to start.

3. Read the steps in order, looking only at operationId and successCriteria.

   Result That is the sequence and the definition of each step working. The parameter plumbing can wait.

4. Read the workflow's outputs.

   Result You know what you are left holding when it finishes, which is usually the thing you actually wanted.

The one habit worth forming is treating successCriteria as the real documentation. A step's description says what it is for; its criterion says what counts as having done it, and those two disagree more often than anyone would like.

Limits#

• Arazzo describes sequences of API calls. It is not a workflow engine, has no runtime and schedules nothing.
• It inherits whatever the underlying API can do. A description cannot make an operation idempotent or a failure recoverable.
• Tool support is thinner than OpenAPI's, so a published document is often read by people before it is read by generators.
• Only public, unauthenticated sequences are worth publishing this way. A workflow across authenticated endpoints belongs in the documentation for the audience that can call them.

Questions#

Related#

• OpenAPI
• AsyncAPI
• The Arazzo workflows
• The public API
• End-to-end workflows