The API Workflow Specification – The Missing Piece of the API Puzzle
Frank Kilcommins is the Principal API Technical Evangelist at SmartBear and a member of the OpenAPI Initiative’s governance board. In this article, he discusses a new specification he is working on under the Open API Initiative: the workflow specification.
Companies are using APIs without proper documentation. This hinders your teams’ ability to discover the APIs. It then hinders the adoption of APIs because if you build APIs that other teams can’t find, they won’t be used. Ultimately, that will impact the success of an API and, maybe even more broadly, a whole API program. Even with the ability of OpenAPI and AsyncAPI, the experience being delivered is not at par. There is an alignment gap across the industry.
Only 48% of those surveyed are confident that the APIs they deliver are well documented and explain the business value on offer. Approximately 43% are unsure that they have the processes to deliver the developer experience they would expect if they put themselves in the consumer seat. Having APIs is necessary if you want to participate in the digital economy. It’s a great way to start leveraging those capabilities that you have on offer.
You must follow a sequence of steps to achieve a value-oriented use case or to extract value from the API. So far, industry specifications have not helped much describe how this can be done.
The workflow specification has been crafted under the OpenAPI special interest group, and it describes an approach to document use case-orientated workflows in a programmatic readable format. A workflow is a series of API calls that accomplish some business objective together. The additional human-readable nature improves the ability of documents crafted using that specification to tell the story of an API in a manner that can elevate the consumer experience.
As a working group, we have worked quite hard to prioritize the different use cases we’re focusing on. We see it as offering the ability to provide deterministic recipes for the use of APIs to make sense of large, unwieldy API descriptions that might have 50 or 100 different endpoints in it and also bridging the very common scenario where business flows span more than a single API, document or description.
We think workflows can improve the ability to have living API documentation to improve the consumer experience. For example, when we onboard consumers to get access to this API, we will give them access to those technical reference documents. But we will accompany that with many other flavors of documents crafted in more human-friendly approaches.
When it comes to code generation, we see a real advantage in having targeted SDK or code generation workflows and documents, which are driven predominantly by business-oriented use cases.
We’re also working with many regulatory bodies to talk about the ability of workflows to allow these bodies to assert and check across the different providers operating within those regulatory areas.
We’re also very excited about the potential for all the innovation happening within AI. We are allowing AI models to have a mechanism to extract value through interaction with workflows. So rather than having to customize how we deliver our APIs or decorate our APIs with many custom attributes, we now can have something that is very easy for the different AI companies to build a natural language layer on top. This will be interoperable, so we don’t have to do something different for every API model.
Workflow specification structure
The structure is quite similar to OpenAPI. First is the “Info” object. This is metadata about the specific workflows, description, or document itself. Next would be “Source Descriptions”. This lists the various other API documents like an OpenAPI description that can be referenced by one or more workflows within the current workflow that we’re describing. This sets the boundary or scope regarding where and what the workflows can operate over. Next is the “Workflow”. It describes the workflows to be taken across one or more APIs to achieve that business value outcome. Each workflow will have an ID, a description summary, input steps, and outputs. Inputs are JSON schema objects required for the workflow to get up and running. Some workflows might need an API key or some other static information that will be required and can’t be dynamically determined by the workflow itself. This is followed by Workflow steps. Each step will represent a call to an API or another workflow. It will also have success criteria and steps to handle failure. Finally, it will have the outputs.
To conclude, this is being worked on, and the feedback round from the open API Technical Steering Committee and technical developer communities ended on 1st December 2023. Hopefully, you can see that the workflow specification is something very exciting that we’re working on under the Open API Initiative. We do think it’s the missing piece of the API puzzle.
