The Arazzo Specification: A Tapestry for API Workflows

A presentation at APIDays Helsinki and North in May 2024 in Helsinki, Finland by Frank Kilcommins

Slide 1

Slide 1

The Specification #apidays

Slide 2

Slide 2

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 */

Slide 3

Slide 3

Slide 4

Slide 4

GIF by Butler University

Slide 5

Slide 5

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%

Slide 6

Slide 6

Slide 7

Slide 7

Slide 8

Slide 8

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.

Slide 9

Slide 9

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

Slide 10

Slide 10

Specification Structure

Slide 11

Slide 11

Metadata about the defined Arazzo Document

Slide 12

Slide 12

Metadata about the defined Arazzo Document

Slide 13

Slide 13

Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows

Slide 14

Slide 14

Metadata about the defined Arazzo Document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows

Slide 15

Slide 15

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.

Slide 16

Slide 16

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.

Slide 17

Slide 17

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

Slide 18

Slide 18

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

Slide 19

Slide 19

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)

Slide 20

Slide 20

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)

Slide 21

Slide 21

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

Slide 22

Slide 22

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

Slide 23

Slide 23

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

Slide 24

Slide 24

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

Slide 25

Slide 25

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

Slide 26

Slide 26

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

Slide 27

Slide 27

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

Slide 28

Slide 28

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

Slide 29

Slide 29

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

Slide 30

Slide 30

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

Slide 31

Slide 31

Reusable (referenceable) components and objects

Slide 32

Slide 32

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

Slide 33

Slide 33

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

Slide 34

Slide 34

Slide 35

Slide 35

Slide 36

Slide 36

My Arazzo Specification GPT

Slide 37

Slide 37

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

Slide 38

Slide 38

Thank You! Questions? › Connect: @fkilcommins @frank-kilcommins frank.kilcommins@smartbear.com