Arazzo Specification, what are they and what are they for?

The recent emergence of Generative AI has increased interest in the world of APIfication, due to its relevant role in this context.

There is no doubt that the union of the two worlds, Generative AI and APIs, forms a nucleus of technological innovation with great potential.

Regardless of the company or sector, or even the type of architecture, sound mechanisms are needed for the consumers of APIs, be they systems, humans or AI, and it goes without saying that this solvency is often lacking.

It is in this sense of facilitating the consumption of APIs that the figure of the API Workflows specification emerges, whose fundamental objective is to describe and document business processes in a standardised way. In other words, they become a key component for two reasons:

• They are a link between Generative AI and APIs
• They inherently aim to improve the developer experience

What does it consist of?

API Workflows Specification is a ground-breaking framework that seeks to define and document API call flows, i.e. it standardises the sequence of calls to different APIs, incorporating success conditions for each step and instructions for passing the response to the next link in the chain.

This work is part of the OpenAPI initiative and enables consumers to make endpoints not only easier to understand, but also easier to consume and integrate, making them easier to adopt and use for both traditional consumers and the new wave of Generative AI consumers.

Objectives

In this first release of API Workflows, the OpenAPI initiative has worked to define and solve a number of common problems that define the initial goals of the workstream, which are to:

• Provide a deterministic “formula” for consuming different APIs. The key factor in consuming APIs is integration, as shown in the Postman report, where 67% of respondents highlighted integration between internal applications, programs or systems as a key issue.

• Act as living documentation and avoid reliance on other resources to produce such documentation.
  It is not new that one of the biggest barriers to consuming APIs is poor or even non-existent API documentation, a fact noted in the Postman and SmartBear reports:
  “52% of respondents said lack of documentation was the biggest problem.”

“Only 32% of respondents said they considered their APIs to be well documented.”

• Provide a coherent and interoperable mechanism for AI models to interact with APIs.
  The use of this type of tool is already commonplace in the development world, and of course it will be no less common in the API world, as the following data shows:
  “60% of respondents reported using these tools. The most common uses were to find bugs in code, to generate code and coding instructions, and to generate documentation.

Structure of the specification

The API Workflows specification is in pre-release version 1.0.0. This means that the initiative is still working on releasing its first official version.

This specification defines the structure of the document(s) describing the call flows in both JSON and Yaml format, and the following image shows the details of its components in a very summarised form:

A step-by-step example of the specification to better understand the structure would be: presentation by Frank Kilcommins from which we have extracted the image above or examples from the OpenAPI initiative, where they are standardising typical flows found in real scenarios to use as a basis.

The way it works is very simple: within each workflow you define the possible parameters or inputs for that flow and the list of actions or steps that are formed based on certain conditions, as shown in the image below:

When we talk about testing, how can it help us?

In the field of testing, the use of API Workflows allows us to solve one of the most common challenges we face: the validation of information flows. With today’s tools, such validation requires a lot of effort from teams, regardless of their testing toolkit.

The current approach is based on testing individual endpoints at the acceptance and/or integration level, rather than focusing on business processes, because building such complete scenarios requires a lot of effort and is a type of testing that is not performed. At best, it is done for critical business processes, but this is not the norm.

The use of API Workflows allows us to define system-readable test scenarios that contain all the necessary information: operations, sequence, expectations... without having to spend time and effort implementing the process.

This allows us to create test plans based on real scenarios, rather than one-off tests, which are more effective and guarantee the expected behaviour from the end user’s point of view.

And of course, what is the role of Generative AI in this area?

Throughout this article we have been talking about generative AI, and this is no coincidence. The synergy that exists between the specification of API workflows and Generative AI is undeniable, as workflows serve as a link between the functionalities offered by APIs and the processing capabilities of the AIs that consume them.

In other words, workflows not only facilitate consumption by developers or traditional systems, but also provide a standardised interface for Generative AI to interact in a more efficient way, with the following benefits:

• It facilitates and standardises interactions
  From the point of view of AI as a consumer of services, it is crucial to have a compressible and defined flow of interactions and calls to APIs, allowing complex operations to be performed within a coherent and unified framework of services, for which standardisation is essential.
• It speeds up the adoption and use of Generative AI
  By simplifying interactions, developers can create applications that take advantage of the capabilities of Generative AI, not only reducing development time, but also incorporating new features based on innovation.
• It promotes security
  API Workflows ensure that operations performed by Generative AI through exposed APIs are secure and compliant, following validated security protocols and compliance requirements, minimising risk and potential information leakage.

Conclusions

In summary, the work done so far by the OpenAPI initiative with the API Workflows specification, and which is still ongoing, enables us to:

• Simplify the use of APIs by providing a clear and deterministic “recipe” for using APIs together, rather than in isolation as is currently the case. This significantly reduces the learning curve and improves the efficiency of integration.
• Consult dynamic and living documentation as it ensures that the specification is up to date, reliable and accurate in terms of the functionality it describes.
• Improve the developer experience by acting as a liaison between API providers and their consumers.
• Improve security and compliance. It is easier to increase security measures and incorporate necessary regulations when there is a standardised basis to build on.

We think this is an initiative to keep an eye on, as it will give us a lot to talk about and, of course, to incorporate into our stack once a stable version is released.

References

• The API Future is Bright with the New API Workflows Specification
• Git Hub Arazzo-Specification
• Redefine API Testing with the OpenAPI workflows
• Post by David Roldán on Innovating API integrations with AI