A presentation at APIDays London in in London, UK 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 /* 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 definitions › Bridge the gap where business flows span more than one API definition › 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 Describes source documents (e.g., OpenAPI document) 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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
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
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
The API Workflows Specification, being developed under the OpenAPI Initiative, which aims to compliment current specifications such as, OpenAPI and AsyncAPI, by enabling the ability to define and document workflows, which are a series of API calls that together accomplish a specific business objective. This will provide a deterministic recipe for using APIs and enable code generation tooling for a given API(s) based on use-cases. Additionally, the specification will improve regulatory checks, bridge gaps where use-case flows span multiple API definitions. In general, there’s enormous potential to enhance the developer experience (DX) and API documentation by enabling graphical rendering of workflows, the specification will improve human understanding of how to consume API endpoints to achieve a goal. Workflow documents can stay up to date and be assertable against the underlying APIs, reducing the need for out-of-band documentation sharing, and reduce the time and effort required to implement complex workflows, and automate testing and other repetitive tasks. Overall, the API Workflows Specification will improve the capability of API specifications to tell the story of the API(s) in a manner that can improve interoperability across many industries.
for free. You
can too.