The Specification #apidays
A presentation at APIDays Helsinki and North in May 2024 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
