In June 2024, the OpenAPI Initiative announced the first version of their new workflow specification, Arazzo. We’ve already mentioned Arazzo (in its unbranded form) in our post on linking API requests as a means to describe a sequence of related API calls. At version 1.0.0, Arazzo, the Italian word for “tapestry,” is designed to meet the needs of API providers and consumers in providing descriptions of sequences of API calls for end-to-end technical or business flows.

The Arazzo Specification: A “tapestry” for deterministic API workflows.

As the meaning of the name implies, how Arazzo can help is clear. The API economy is built on cloud-based platforms, with many organizations implementing increasingly complex flows that require interactions with multiple platforms. To date, describing this accurately has been done in isolation. Like APIs before API description languages, defining complex flows has primarily been done in code or through visual integration builders that support integration and iPaaS solutions. But now, Arazzo supports weaving together different API calls and descriptions into a single picture to provide clarity for workflow consumers.

As with most subjects, however, more context can aid understanding, so it’s worth looking at some real-life use cases for the Arazzo Specification.

Linking API Security and API calls

The first area where Arazzo could help is by linking API security and making API calls. Generally speaking, there is a separation between security endpoints that require calling a URL that “looks like” an API and the API descriptions you need for calling an API that your client has been granted access to. OpenAPI descriptions include the Security Scheme Object, but this rarely bridges the gap between indicating the prescribed security flow and making an actual API call based on a token you’ve elicited from the security flow. The decoupled nature of the security flow is often exacerbated by the source of security implementations, which come from a specific vendor with separately-maintained API descriptions.

The separation between security and functional APIs may not seem like an issue on a case-by-case basis, but they are significant in terms of open standards. Having the means to accurately describe the sequence of API calls, including security, for an entire ecosystem is extremely valuable due to the number of questions it can answer, easing the implementation of standards for initiatives like open banking.

The Arazzo team has already been thinking about this use case, and you can find examples in the Specification repository of flows that call multiple OAuth endpoints to authorize access and issue access tokens. They describe using the OAuth grant type to retrieve an authorization code, swapping this out for an access token, and finally using it to call an API.

Providing Employee Performance Data for Human Resource Management Platforms

Human resource management (HRM) SaaS solutions are another area where an Arazzo description can help. HRM solutions (and the APIs that support them) are increasingly popular as large organizations move their HR solutions to the cloud and take advantage of managed solutions. However, an HRM platform does not operate in isolation. For example, how do you automatically retrieve sales commissions in Salesforce so they can be captured against a given employee record in your BambooHR instance? What about employee tax records recorded in a payroll system, in the HRM platform, and submitted externally to the tax authorities?

HRM integrations are littered with flows like this, many of which can be described using the Arazzo Specification. If you are creating your integrations yourself, you may not be interested in describing your flow other than as a means to document your work. However, if you are a unified API provider like Apideck or Unified, then using Arazzo to document flows available to your customers can be very useful.

Using Arazzo can help create repeatable, well-defined workflows to enhance the key selling point of a unified API, namely that you can address multiple platforms through one API. Regardless of whether you are a unified API provider, Arazzo can help you describe your integration with HRM and other platforms, which could help you accurately document your workflow.

Booking Specialist Treatment in Healthcare Systems

Healthcare systems could also benefit from the use of Arazzo. Healthcare provision increasingly relies on an electronic health record (EHR) as the primary means to record appointments, diagnoses, and treatments for a given patient. While EHRs provide a system of record for the patient, the number of ways the EHR can be changed and updated in the healthcare ecosystem is vast and dependent on interactions with many other systems. Many countries have centralized bodies that help govern healthcare IT, and in such countries, Arazzo could be of considerable benefit in creating standardized workflows for activities such as treatment booking.

Take the case of booking an appointment for a knee dislocation, for example. The first step is to retrieve the patient’s EHR. The patient ID and condition code for a knee dislocation are used as the inputs to the flow. The inputs to be defined in a Workflow Object:

- workflowId: BookTreatment
  summary: Book treatment for a given condition
  description: Provide a patient identifier and condition code to secure an appointment for a given condition
  inputs:
    type: object
    properties:
      patientId:
        description: Patient identifier
        type: string
      conditionCode:
        description: Standardised condition code
        type: string

The first Step Object then retrieves the EHR and locates the knee dislocation treatment reference code that provides the tracker for the specific patient diagnosis. The reference to the correct operation in the underlying API is provided by the operationId, which points to the getEhr operation on the EHR platform:

- step: GetEhrCondition
  operationId: ehrPlatform.getEhr
  parameters:
  - name: patientId
    in: body
    value: $inputs.patientId
  - name: conditionCode
    in: body
    value: $inputs.conditionCode
  successCriteria:
  - condition: $statusCode == 200
  outputs:
    treatmentReferenceCode: $response.body.treatmentReferenceCode

With the reference code in hand, the application code can find the correct step that describes calling the orthopedics platform to book a consultant appointment:

- step: BookOrthopedic
  operationId: orthopedicsPlatform.bookOrthopedicsConsultant
  parameters:
  - name: patientId
    in: body
    value: $inputs.patientId
  - name: treatmentReferenceCode
    in: body
    value: $steps.GetEhrCondition.outputs.treatmentReferenceCode
  successCriteria:
  - condition: $statusCode == 200
  outputs:
    appointmentId: $response.body.appointmentId
    appointmentDateTime: $response.body.appointmentDateTime

The Arazzo Specification can also describe steps that include updating the EHR, booking subsequent appointments with different providers, and providing costs to insurers where patients have consented to share such information directly with their insurance company.

Healthcare is, therefore, a use case for Arazzo that could offer significant benefits, providing comprehensive descriptions for API consumers that could engender efficiencies in platform integration. Any efforts to lower the cost of system integration through increased efficiency are welcome in most economies, given the significant burden of healthcare provision on the taxpayer.

Going Beyond Use Cases: What’s Next for the Arazzo Specification?

We have looked at three use cases for Arazzo (without mentioning generative AI) and can conclude that using Arazzo to describe sequences of API calls stacks up. However, we talk about many standards on the Nordic APIs blog. One key, overarching theme apparent in all of them is tooling support. The utility of standards like the Arazzo Specification is only as good as the community that supports them.

It’s early days for Arazzo and the development of supporting tooling in the community. The implementers’ draft was around for a while, and vendors have already been exploring Arazzo’s potential. However, support for Arazzo in open-source and commercial software will take time to filter through.

There’s also the question of future development. Currently, inputs to an Arazzo description are limited to OpenAPI descriptions and other Arazzo descriptions. AsyncAPI will be coming into scope next, and other API styles and description formats could be supported in future versions.

An Arazzo description can make integration easier for many use cases. Fostering strong support in the tooling community and integrating more API description formats will help turn what Arazzo aims to achieve into reality.

We will be keeping an eye on the development of Arazzo and the growth of the Arazzo community, so please check back on the blog in the future for more updates.