A presentation at APIDays Paris in in Paris, France by Frank Kilcommins
The Workflows Specification The missing piece of the API puzzle? #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 Workflows Specification › Connect: @fkilcommins @frank-kilcommins frank.kilcommins@smartbear.com /* insert embarrassing photo here */
Talk Track › › › › › What is the Workflows Specification Use cases Workflows Specification structure Example Q&A
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 Workflows 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 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
Workflows Specification Structure
Metadata about the defined workflows document
Metadata about the defined workflows document
Metadata about the defined workflows document Lists source descriptions (e.g., OpenAPI description) that can be referenced by one or more workflows
Metadata about the defined workflows document Describes source documents (e.g., OpenAPI document) that can be referenced by one or more workflows
Metadata about the defined workflows 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 workflows document Describes source documents (e.g., OpenAPI document) 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 workflows 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 workflows document Describes source documents (e.g., OpenAPI document) 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 workflows 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 workflows document Describes source documents (e.g., OpenAPI document) 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 workflows 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 workflows document Describes source documents (e.g., OpenAPI document) 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 workflows 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 workflows document Describes source documents (e.g., OpenAPI document) 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 workflows 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 workflows document Describes source documents (e.g., OpenAPI document) 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 workflows 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 workflows document Describes source documents (e.g., OpenAPI document) 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 workflows 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 workflows document Describes source documents (e.g., OpenAPI document) 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
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
What’s the status? › Feedback round from the OAI TSC & TDC ended Dec 1st › Implementor DRAFT ready for LAUNCH › https://www.openapis.org/ being updated to include the new specification
Learn more › Workflows Specification › https://github.com/OAI/sig-workflows/blob/main/versions/1.0.0.md › Examples: › https://github.com/OAI/sig-workflows/tree/main/examples/1.0.0 › Current Examples: › › › › OAuth FAPI-PAR LoginAndRetrievePets Pet-Coupons
Thank You! Questions? › Connect: @fkilcommins @frank-kilcommins frank.kilcommins@smartbear.com
Learn about the API Workflows Specification, developed under the OpenAPI Initiative, which complements current specifications, including OpenAPI and AsyncAPI. The new specification enables the ability to define and document workflows, a series of API calls, that together accomplish a specific business objective.
This provides a deterministic recipe for using APIs and enables code generation tooling for a given API based on use-cases. Additionally, the specification improves regulatory checks and bridges gaps where use-case flows span multiple API descriptions.
In general, there’s enormous potential to enhance the developer experience (DX) and API documentation by enabling graphical rendering of workflows. The specification also improves human understanding of how to consume API endpoints to achieve a specific goal.
Workflow 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 Workflows Specification improves the capability of API specifications to tell the story of the API in a manner that improves interoperability across industries.
for free. You
can too.