OpenAPI describes individual operations: here is an endpoint, here is what it takes, here is what it returns. But almost no real work happens in one call. Onboarding a customer, processing a payment, fulfilling an order — each is a sequence of calls in a particular order, passing data between steps, with dependencies and branches.
That sequence is a workflow, and until Arazzo there was no standard machine-readable way to describe one. Every provider expressed their workflows as prose in a tutorial, which meant no machine could read them, no test could verify them, and every consumer reimplemented them by hand from the docs.
Arazzo closes the gap between operations and outcomes. And it is the artifact whose moment has clearly arrived, because an agent trying to accomplish a task needs exactly this: not a list of 200 endpoints, but a description of the four calls that get the job done and how the output of one feeds the next.
Where to start: take the three most common things consumers do with your API — the ones your tutorials already cover in prose — and write them as Arazzo workflows. You will discover design problems in the process, because a workflow that is awkward to describe is usually a workflow that is awkward to execute.
