A presentation at APIDays Helsinki and North in in Helsinki, Finland by Frank Kilcommins
The Specification #apidays
I’m Frank Kilcommins › › › › Principal API Technical Evangelist @ SmartBear Developer and Architect ( APIs & Developer Experience) Governance Board member on OpenAPI Initiative (OAI) Contributor on the Arazzo Specification › Connect: @fkilcommins @frank-kilcommins frank.kilcommins@smartbear.com /* insert embarrassing photo here */
GIF by Butler University
Alignment Gap › Only 48% are confident their APIs are well documented and explain value for consumers Our APIs are well documented for our consumers Agree 38% Neutral 30% Disagree 16% Strongly Agree 10% Strongly Disagree 2023 5% 0% 10% 20% 30% 2021 40% Our organization has good processes in place to ensure APIs can be efficiently consumed › ~43% unsure their processes will deliver appropriate developer experience (DX) Agree 45% Neutral 27% Disagree 12% Strongly Agree 12% Strongly Disagree 2023 2021 4% 0% 5% 10% Source: SmartBear – State of Software Quality | API 2023 15% 20% 25% 30% 35% 40% 45% 50%
What is the Arazzo Specification? › It describes an approach to document use-case oriented workflows in a programmatically readable format. › A workflow is a series of API calls which when woven together accomplish some business objective. › The additional human readable nature improves the ability of API specifications to tell the story of the API(s) in a manner that can improve the consuming developer experience.
Use cases › Deterministic recipes for the use of APIs › Make sense of large unwieldy API description › Bridge the gap where business flows span more than one API description › Living API documentation and improved consumer developer experience (DX) › Assertable business value › Targeted code generation tooling for APIs driven by use cases › Improved regulatory checks via assertable workflows › The AI potential for value orientated interaction with APIs
Specification Structure
Metadata about the defined Arazzo Document
Metadata about the defined Arazzo Document
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows Describes the workflows to be taken across one or more APIs to achieve an objective/outcome.
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows Describes the workflows to be taken across one or more APIs to achieve an objective/outcome.
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows Describes the workflows to be taken across one or more APIs to achieve an objective/outcome. A JSON Schema object representing the inputs used by this workflow
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows Describes the workflows to be taken across one or more APIs to achieve an objective/outcome. A JSON Schema object representing the inputs used by this workflow
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows Describes the workflows to be taken across one or more APIs to achieve an objective/outcome. A JSON Schema object representing the inputs used by this workflow The defined workflow steps, each representing a call to an API operation (or another workflow)
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows Describes the workflows to be taken across one or more APIs to achieve an objective/outcome. A JSON Schema object representing the inputs used by this workflow The defined workflow steps, each representing a call to an API operation (or another workflow)
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows Describes the workflows to be taken across one or more APIs to achieve an objective/outcome. A JSON Schema object representing the inputs used by this workflow The defined workflow steps, each representing a call to an API operation (or another workflow) A list of parameter objects, representing parameters to pass to an operation or workflow
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows Describes the workflows to be taken across one or more APIs to achieve an objective/outcome. A JSON Schema object representing the inputs used by this workflow The defined workflow steps, each representing a call to an API operation (or another workflow) A list of parameter objects, representing parameters to pass to an operation or workflow
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows Describes the workflows to be taken across one or more APIs to achieve an objective/outcome. A JSON Schema object representing the inputs used by this workflow The defined workflow steps, each representing a call to an API operation (or another workflow) A list of parameter objects, representing parameters to pass to an operation or workflow An array of failure action objects that specify what to do on step failure
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows Describes the workflows to be taken across one or more APIs to achieve an objective/outcome. A JSON Schema object representing the inputs used by this workflow The defined workflow steps, each representing a call to an API operation (or another workflow) A list of parameter objects, representing parameters to pass to an operation or workflow An array of failure action objects that specify what to do on step failure
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows Describes the workflows to be taken across one or more APIs to achieve an objective/outcome. A JSON Schema object representing the inputs used by this workflow The defined workflow steps, each representing a call to an API operation (or another workflow) A list of parameter objects, representing parameters to pass to an operation or workflow An array of failure action objects that specify what to do on step failure An array of success action objects that specify what to do upon step success
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows Describes the workflows to be taken across one or more APIs to achieve an objective/outcome. A JSON Schema object representing the inputs used by this workflow The defined workflow steps, each representing a call to an API operation (or another workflow) A list of parameter objects, representing parameters to pass to an operation or workflow An array of failure action objects that specify what to do on step failure An array of success action objects that specify what to do upon step success
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows Describes the workflows to be taken across one or more APIs to achieve an objective/outcome. A JSON Schema object representing the inputs used by this workflow The defined workflow steps, each representing a call to an API operation (or another workflow) A list of parameter objects, representing parameters to pass to an operation or workflow An array of failure action objects that specify what to do on step failure An array of success action objects that specify what to do upon step success A map between a friendly name and a dynamic output value for a step
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows Describes the workflows to be taken across one or more APIs to achieve an objective/outcome. A JSON Schema object representing the inputs used by this workflow The defined workflow steps, each representing a call to an API operation (or another workflow) A list of parameter objects, representing parameters to pass to an operation or workflow An array of failure action objects that specify what to do on step failure An array of success action objects that specify what to do upon step success A map between a friendly name and a dynamic output value for a step
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows Describes the workflows to be taken across one or more APIs to achieve an objective/outcome. A JSON Schema object representing the inputs used by this workflow The defined workflow steps, each representing a call to an API operation (or another workflow) A list of parameter objects, representing parameters to pass to an operation or workflow An array of failure action objects that specify what to do on step failure An array of success action objects that specify what to do upon step success A map between a friendly name and a dynamic output value for a step A map between a friendly name and a dynamic output value for a workflow
Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows Describes the workflows to be taken across one or more APIs to achieve an objective/outcome. A JSON Schema object representing the inputs used by this workflow The defined workflow steps, each representing a call to an API operation (or another workflow) A list of parameter objects, representing parameters to pass to an operation or workflow An array of failure action objects that specify what to do on step failure An array of success action objects that specify what to do upon step success A map between a friendly name and a dynamic output value for a step A map between a friendly name and a dynamic output value for a workflow
Reusable (referenceable) components and objects
Creating a Pet Adoption Service Problem: We’re overwhelmed by the number of pets being abandoned at our pet store. Solution: Following research and evaluation, we’ve decided to create the ability to search for and adopt pets that we catalog. We’ll offer the service via our website but also with a wider eco-system of shelters, charities, and pet orphanages. Photo by Thomas Park on Unsplash
Example Workflow Use Case › Adopt a pet matching specific criteria › Steps: 1. Search for a pet 2. Initiate adoption request 3. Confirm adoption by updating status 4. Verify pet has been updated to adopted
My Arazzo Specification GPT
Call to Action › Join the slack workspace: https://communityinviter.com/apps/openapi/openapi › Star the repo: https://github.com/OAI/Arazzo-Specification › Submit your use cases (as discussions or issues) Learn more › Arazzo Specification: › https://github.com/OAI/Arazzo-Specification/blob/main/versions/1.0.0.md › Examples (OAuth, FAPI-PAR, LoginAndRetrievePets, & more): › https://github.com/OAI/Arazzo-Specification/tree/main/examples/1.0.0
Thank You! Questions? › Connect: @fkilcommins @frank-kilcommins frank.kilcommins@smartbear.com
Officially announcing the Arazzo Specification which enables the ability to define and document workflows, a series of API calls, that when woven together accomplish a specific business objective. The new specification was developed under the OpenAPI Initiative, and complements current specifications, including OpenAPI and AsyncAPI.
Arazzo provides a deterministic recipe for using APIs and enables code generation tooling for a given API based on use-cases. Additionally, Arazzo improves regulatory checks and bridges gaps where use-case flows span multiple API descriptions.
The new specification provides a sufficient level of predictable determinism to AI models, allowing them to offer a natural language abstraction on top of the business use cases, while in parallel giving interoperability benefits to the actual API providers. The result is more value, with less vendor lock-in, and consistent API offerings for both humans and the new wave of AI consumers.
In general, there’s enormous potential to enhance the developer experience (DX) and API documentation by enabling graphical rendering of API workflows. The specification also improves human understanding of how to consume API endpoints to achieve a specific goal.
Arazzo descriptions can stay up-to-date and be assertable against the underlying APIs. This reduces the need for out-of-band documentation sharing, reduces the time and effort required to implement complex workflows, and automates testing and other repetitive tasks. Overall, the Arazzo Specification improves the capability of API specifications to tell the story of the API in a manner that improves interoperability across industries.
The following resources were mentioned during the presentation or are useful additional information.
The Arazzo Specification
for free. You
can too.