Designing with workflows: Using Arazzo and OpenAPI for better API collaboration

The most persistent issue in API development is outdated documentation. What if your documentation was also your test suite, guaranteeing it was always accurate?

Based on a real case, this talk by Roman Hotsiy, CTO at Redocly, presents a practical approach to API development using Arazzo to solve this problem. I'll take you behind the scenes and show exactly how we use this methodology to keep our complex API documentation perpetually in sync. We'll explore how Arazzo's declarative workflows may be used for clear, human-readable descriptions of user journeys that are perfect for docs. Then, I'll show how these same files can be executed against your API in CI, ensuring the documentation is never wrong and helping to avoid OpenAPI drift.

This approach establishes Arazzo as a powerful, central tool for API design and collaboration, going far beyond simple contract testing. It goes beyond simple contract testing, transforming your documentation process from a maintenance burden into a core quality gate.

Transcript

1. Designing with Using Arazzo and OpenAPI for better API collaboration Roman Hotsiy OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA workflows
2. ROMAN HOTSIY CTO @Roman Hotsiy @Roman Hotsiy Originally from Ukraine󰑒, now based in Bali 󰏙 Passionate about APIs 󰞵, surfing 󰝖, and a new baby girl 🐣 OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
3. The collaboration challenge in API design OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
4. The most persistent issue in API development is… The Problem We All Know 24% Source: Postman State of the API 2025 55% Inconsistent documentation 43% Inconsistent definitions 35% Duplicated efforts 34% Discovering existing APIs 30% Managing access 24% Sharing API artifacts Managing security risks 7% None of the above OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
5. OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA Teams often work in silos Product Managers think in user journeys Developers think in endpoints and code. QA & Tech Writers are left trying to glue the two realities together Great APIs are built by teams not individuals
6. OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
7. OpenAPI is our contract, but it's not a conversation It defines the “what”, not the why or the “how” The contract and the implementation tend to drift apart But... Isn't OpenAPI supposed to fix this? OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
8. Let's design the conversation, not just the words. What if we: Incorporate key user journeys into our API design Design is clear enough for humans to read Design is precise enough for a machine to test? OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
9. An additional open-source specification by OpenAPI Initiative for defining multi-step API journeys. For Tech Writers It's the blueprint for a tutorial For Devs & QA It's an executable test case For PMs It's a clear description of a user story Introducing Arazzo: The Spec for Workflows OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
10. Arazzo Anatomy arazzo: 1.0.1 info: title: Warp API reusable workflows version: 1.0.0 sourceDescriptions: - name: api-reference type: openapi url: openapi.yaml workflows: - workflowId: missionLostInvention summary: Lost invention workflow description: |- Travel back to the year 1889 and retrieve the blueprint for Nikola Tesla's lost invention before it's destroyed in a mysterious fire. inputs: # ... inputs schema here parameters: - name: Authorization in: header value: "Bearer {$inputs.token}" steps: - stepId: setAnchorToCurrentTime operationId: api-reference.setAnchor description: Set an anchor to the current time. outputs: anchor_id: $response.body#/id - stepId: jumpTo1889 operationId: api-reference.timeTravel description: Travel to 1889 using the created timeline. requestBody: payload: destination: $steps.setAnchorToCurrentTime.outputs.anchor_id OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
11. Info section arazzo: 1.0.1 info: title: Warp API reusable workflows version: 1.0.0 OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
12. Link your contracts sourceDescriptions: - name: api-reference type: openapi url: openapi.yaml OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
13. Workflows workflows: - workflowId: missionLostInvention summary: Lost invention workflow description: |- Travel back to the year 1889 and retrieve the blueprint for Nikola Tesla's lost invention before it's destroyed in a mysterious fire. inputs: # ... inputs schema here parameters: - name: Authorization in: header value: "Bearer {$inputs.token}" OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
14. Steps steps: - stepId: setAnchorToCurrentTime operationId: api-reference.setAnchor description: Set an anchor to the current time. outputs: anchor_id: $response.body#/id - stepId: jumpTo1889 operationId: api-reference.timeTravel description: Travel to 1889 using the created timeline. requestBody: payload: destination: $steps.setAnchorToCurrentTime.outputs.anchor_id OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
15. Let’s take a bird-eye view again OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
16. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 arazzo: 1.0.1 info: title: Warp API reusable workflows version: 1.0.0 sourceDescriptions: - name: api-reference type: openapi url: openapi.yaml workflows: - workflowId: missionLostInvention summary: Lost invention workflow description: |- Travel back to the year 1889 and retrieve the blueprint for Nikola Tesla's lost invention before it's destroyed in a mysterious fire. inputs: # ... inputs schema here parameters: - name: Authorization in: header value: "Bearer {$inputs.token}" steps: - stepId: setAnchorToCurrentTime operationId: api-reference.setAnchor description: Set an anchor to the current time. outputs: anchor_id: $response.body#/id - stepId: jumpTo1889 operationId: api-reference.timeTravel description: Travel to 1889 using the created timeline. requestBody: payload: destination: $steps.setAnchorToCurrentTime.outputs.anchor_id Readable by humans Project managers can read this is a user-story OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
17. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 arazzo: 1.0.1 info: title: Warp API reusable workflows version: 1.0.0 sourceDescriptions: - name: api-reference type: openapi url: openapi.yaml workflows: - workflowId: missionLostInvention summary: Lost invention workflow description: |- Travel back to the year 1889 and retrieve the blueprint for Nikola Tesla's lost invention before it's destroyed in a mysterious fire. inputs: # ... inputs schema here parameters: - name: Authorization in: header value: "Bearer {$inputs.token}" steps: - stepId: setAnchorToCurrentTime operationId: api-reference.setAnchor description: Set an anchor to the current time. outputs: anchor_id: $response.body#/id - stepId: jumpTo1889 operationId: api-reference.timeTravel description: Travel to 1889 using the created timeline. requestBody: payload: destination: $steps.setAnchorToCurrentTime.outputs.anchor_id OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA Executable by machines Automated tooling can execute it precisely
18. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 arazzo: 1.0.1 info: title: Warp API reusable workflows version: 1.0.0 sourceDescriptions: - name: api-reference type: openapi url: openapi.yaml workflows: - workflowId: missionLostInvention summary: Lost invention workflow description: |- Travel back to the year 1889 and retrieve the blueprint for Nikola Tesla's lost invention before it's destroyed in a mysterious fire. inputs: # ... inputs schema here parameters: - name: Authorization in: header value: "Bearer {$inputs.token}" steps: - stepId: setAnchorToCurrentTime operationId: api-reference.setAnchor description: Set an anchor to the current time. outputs: anchor_id: $response.body#/id - stepId: jumpTo1889 operationId: api-reference.timeTravel description: Travel to 1889 using the created timeline. requestBody: payload: destination: $steps.setAnchorToCurrentTime.outputs.anchor_id OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA Linked to your contract • The request data can be taken from OpenAPI example values Link to the OpenAPI provides you with a free “contract” test • Response codes • Response payload schema • Response headers
19. OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
20. The 3−Step adoption plan How to implement it in your organization? You can't go from zero to a perfect design-first culture overnight. 03 END GOAL Design with Workflows 02 LEVEL UP Reuse 01 START HERE Solve the most immediate pain: fight contract drift OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
21. Step 1. Fight API drift The pitch: "We have a problem with outdated docs and regressions. Let's start testing our key user flows against our spec. This will be our quality gate." Your entry point: Solve the most immediate pain. • An un-reused OpenAPI spec is an untrusted spec • Testing is the simplest, most powerful form of reuse. OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
22. Problems with classic contract testing Tools like Dredd are great for validating a single request/response against your spec. The Problem: They are stateless. They can't test a real user journey. OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
23. Problems with classic integration testing • Tied to a specific stack (JS, Go, Java, etc.) • Imperative Code • Coupled to API implementation vs the public API contract • Audience: Developers only OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
24. Arazzo marries them both. • Arazzo is the bridge that fills the gap. operationId link = Contract Test Chained steps = Integration Test OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
25. Story time We switched our implementation to open standard We learned the Arazzo is the thing Out of the frustration one of the engineers on our team started building our own in-house version of arazzo spec OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
26. Where we are now Regressions prevented It saved us a lot of headache times/day It runs multiple times a day in our CI for each PR Workflows We have a tons of TBD How we did it at Redocly • This is exactly where we began. • Started from our most critical user flows. • This was our first, immediate, massive win. OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA TBD TBD TBD
27. OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
28. OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
29. How you can do it THE SPEC IS NEW SO TOOLING IS STILL EVOLVING. You can use multiple tools to run it in CI: • @redocly/cli respect command • Itarazzo-client • @arazzo/runner Sleep better. You've just created a powerful quality gate. Run it in CI on every pull request. Write the Arazzo file for it. Go back to your team. Pick one critical user journey. OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
30. More reuse = More alignment Step 2 Reuse If contract is not reused in a meaningful way it is deemed to drift Code-First Pitfall: • Code annotations can silently go out of sync Design-First Pitfall: • A beautiful design can be ignored if not enforced Guarantee sync by reusing everything. OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
31. Your specs are a platform. Manual testing Generate collections for popular tools or use a manual testing tool that supports Arazzo Gateways Configure API Gateways Mock servers Power your mock servers Monitoring Continuously monitor the most important workflows AI Expose workflows as MCP tools or skills Interactive guides We have tooling cooking at Redocly. Stay tuned… SDKs Generate SDKs (client libraries) Automated tests Contract + integrations tests Design tool Use it as an API design tool OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
32. This workflow is exposed to the AI as a single, simple, reliable tool (e.g. MCP Arazzo lets you declaratively define that complex workflow using your existing APIs. AI agents struggle to reliably wire together complex, multi-step API calls. A bridge from complex APIs to AI tools OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
33. Coming soon: building a tool for generating interactive guides from Arazzo Generating API reference docs from OpenAPI Generate client SDK for our front-end Continuous monitor the most important flows using “Respect Monitoringˮ How we did it at Redocly OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
34. OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
35. How you can do it 04 Reuse! 03 Remember: you already have the specs! 02 Find appropriate tooling 01 Pick one or more of the use cases for reuse described above OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
36. The final goal: shift left • Make workflows the core of your design • Start using Arazzo + OpenAPI as a design tool • Write the workflow before the code OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
37. Some of the new features start with a Arazzo file in the RFC PR We are still mastering this It was an evolutionary step How we did it at Redocly Step 3 Design with Workflows OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
38. OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
39. How you can do it It may just happen as an evolutionary step Offer help Encourage people to author an Arazzo workflow as a design effort OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
40. Win with Design Grow with Reuse Start with Testing From a Tactical Fix to a Cultural Shift OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
41. Share the Pattern Deliver the Proof Identify the Pain Your Practical Plan for Monday Morning OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA
42. Thank you! Questions? https://u24.gov.ua https://redocly.com Links: Arrazo Specification - https://spec.openapis.org/arazzo/latest.html Redocly CLI - https://github.com/Redocly/redocly-cli OCT 30, 2025 DESIGNING WITH WORKFLOWS APIDAYS AUSTRALIA