Documenting API Workflows with Arazzo - by Bruno Pedro
An API is as useful as the use cases it can fulfill. And use cases usually involve more than one single API operation. The best way to describe them—until now—is to use code or write them down as a recipe. While code makes use cases machine-readable, documentation makes them easy to understand. Now you can have the best of both worlds by using the Arazzo specification.
Scalar is a suite of powerful & customizable developer tools to help you at all stages of API development. Create beautiful API Documentation in a notion-like editing experience.
Most people are familiar with services that automate the connection with one or several APIs in an orchestrated way. So-called "no-code" services offer an easy way to set up several operations involving multiple APIs. I wrote about how this category of integration products has evolved since the 2010s. "One approach that gained the most popularity over the years is to provide a visual User Interface. Users can see how different parts of an integration connect to each other and can quickly change the connections visually."
Seeing how different parts of an integration interact is crucial to understanding how data flows. Knowing how data flows is important. You get to understand not just what APIs—and operations—contribute to a workflow, but also the business logic applied to each call. That's why most solutions have put effort into visually describing the shape of integrations. While the visual UI is what you see, behind the scenes each solution uses its own definition paradigm.
