The API Future is Bright with the New API Workflows Specification

  January 11, 2024

As 2024 gains momentum, the outlook for APIs is more fascinating than ever. It’s not that APIs have lost any momentum over the last period, but the recent boom of AI has rejuvenated interest. The intersection of AI and APIs is arguably the nucleus of technological innovation moving forward.

Other hot topics for APIs cover the advancement of the APIs-as-products movement – meaning APIs offered by non-software companies will form a fundamental part of their revenue stream – and the challenge of managing the full lifecycle for such products becomes crucial.

We’ll also see the calming of the rush towards microservices. And as we all increase our portfolio of digital capabilities, the need for better security and heightened regulation across many industry verticals engaged with APIs is imperative.

Regardless of company or industry, or whether your technical architecture is monolithic, micro-services, or even micro-monolithic, you need a robust mechanism to express and validate the value on offer by the APIs you deliver. This is especially important when your consumers (human or AI) need to do more than just a single API call to get their job done.

And let’s be clear, this is almost 100% of the time.

This blog is part of #APIFutures, a community-led, collaborative effort to identify the top challenges and opportunities facing the API economy in 2024. For other interesting perspectives, check out the articles by other authors listed here.


The need for workflows and the formation of a Special Interest Group

In the context of API descriptions, you’d usually want to be able to express specific sequences of calls, and articulate the dependencies between them to achieve a particular goal. The quicker you can surface this information, the more likely your consumer can evaluate, understand, and adopt your offering.

From a specifications perspective, the API industry hasn’t really supported that goal, especially in a standardized manner across modern API stacks.

Realizing this gap led us to the formation of a special interest group (SIG) under the OpenAPI Initiative (OAI) to focus on the problem. The working group identified several prominent use cases, and the net result of our efforts over the past year spawned a new API Workflows Specification.

With OAI’s formation and operating of working groups, it’s evolved beyond a single specification entity, and it now has field experts work on priority topics of broad relevance across the API space. Exciting times!

Introducing the Workflows Specification

The OAI’s Workflows Specification helps you define and document workflows – a series of API calls – that work together to accomplish a specific business objective.

Figure 1 — The API Workflows Specification structure

The specification helps you craft workflows in a human- and machine-readable manner. This helps explain the API capabilities in a way that’s easier for developers to consume. API endpoints are understood and consumed faster, making it easier to achieve a specific goal for traditional human consumers – as well as the new wave of AI consumers.

With the assertable nature of the crafted workflows, we can tackle many challenges faced by teams across the API landscape and create new possibilities for the next generation of API consumers. Plus, it improves rigor for regulatory bodies.

Use-cases and challenges

The following represent the primary set of use cases targeted by the working group and catered to by the initial version of the Workflows Specification.

  • Provide deterministic recipes for using APIs
  • Act as living documentation and negate the dependence on out-of-band API documentation
  • Provide assertable qualities for providers, consumers, and regulatory stakeholders
  • Empower the next wave of API SDK generation
  • Provide a consistent and interoperable mechanism for AI models to interact with APIs

Provide a deterministic recipe for using APIs

Teams need to organize their API endpoints to make them understandable for consumers. In a monolithic approach, it’s common for an API description (e.g., an OpenAPI description) to become unwieldly and contain tens, even hundreds of endpoints.

On the flip side, if the structure is too modular then most consumer use cases will need to interact with multiple API descriptions.

Figure 2 – Alignment gap in delivered quality versus expectation - SmartBear SOSQ API Report 2023

In both situations, it’s important to articulate the expected consumption flows towards consumers, and to ensure that the business value is clearly represented to API adopters. To use existing specifications is beneficial but the industry is still not confident (see Figure 2) that they are delivering the expected developer experience.

This is one area where the Workflows Specification shines. It goes beyond the typical confines of API descriptions, exploring how numerous APIs endpoints can be orchestrated cohesively and with purpose regardless of being spread across multiple description files. It can be leveraged to describe complex processes with many API calls, making things clear and organized towards consumer needs.

This is important when APIs are part of a bigger system. The Workflows Specification lets teams clearly define interactions, ensuring that API processes are easy to predict, handle, and expand. This affordance lets providers describe the specific use cases on offer to solve consumer challenges regardless of their endpoint grouping strategy.

Act as living documentation for APIs

Technical reference documentation, like OpenAPI descriptions, form only one piece of the API documentation needs for consumers. In truth the anatomy of good API documentation is composed of various types of documentation – reference, concepts, tasks. Even in 2024, we still must rely on manually created artefacts to address the concepts covered by our APIs, and tasks to be executed to extract value from them.

The mediums to express these documentation types is still predominantly in static form – like HTML or Markdown content within a developer portal page. Worse still, it’s often shared in a completely out-of-band manner using more human-readable formats like PDF, MS Word, Google Docs, slides, images, etc.

The biggest issue with such approaches is that once created, these artefacts quickly become dated, and if they’re not manually updated they’re quickly untrustworthy. We envisage that the initial wave of tooling built around the Workflows Specification will provide the ability to render the specification in graphical form for consumers – no more manually created flow/sequence diagrams!

Maintaining accuracy between API documentation and its actual implementation is another significant challenge the working group dove into. Changes in provider code may not always be promptly reflected in the documentation, easily leading to discrepancies.

This can confuse developers who rely on accurate documentation to integrate and interact with the API effectively. Alignment between the documentation and implementation is crucial. Most industry focus in this area goes to ensuring that the API can honor the promise made by the design, but there are little mechanisms to ensure that expected business flows are still achievable and correctly represented, especially if that flow spans more than a single API. This is made even more difficult if the APIs are owned by different teams.

The Workflows Specification acts as a façade on top of the underlying API descriptions and is focused on the priority consumer business flows. We’re confident that the specification provides a unique ability for teams to insert more rigor into their processes by leveraging the produced Workflows description as living assertable documentation. They can verify that extensions and changes to the underlying APIs do not break the expected use cases.

Provide assertable mechanisms for business value

To regard documentation as living, you need to trust that it’s always accurate. The Workflows Specification addresses this fundamental need for an assertable mechanism at many levels.

From a micro-level perspective, it empowers teams (through the tooling that will be built up in support of the specification) to validate that the promises they make to consumers are always achievable, even as they evolve and deliver changes through their API portfolio.

On a macro-level, the working group is engaged with regulatory and standards bodies that intend to leverage the Workflows Specification as a mechanism to apply regulatory checks and benchmarking.

For example, for Open Banking, this will allow various jurisdiction regulatory bodies to validate if providers meet regulatory requirements by executing an assertable workflow against the provider implementation. This provides assurance that the intended requirements are being met by providers for a particular market.

It's worth noting that being able to classify and assert “how” APIs are expected to be consumed can have security benefits too. Observing real-time API consumption and asserting it against defined workflows gives the ability to specifically manage the Unrestricted Access to Sensitive Business Flows vulnerability that is part of the new OWASP Top 10 risks for APIs.

Empower API client and SDK generators

Many API consumers rely on code generators to bootstrap the creation of client applications and streamline their process for getting an API integrated. From a provider perspective, many prefer to invest in taking this client need to the next level and expose a Software Development Kit (SDK) towards consumers rather than direct API access.

An SDK can simplify integration by offering pre-built functions, reducing development time and potential errors. It can improve developer experience through documentation, code samples, and often includes tools for debugging. If done right, SDKs abstract complexity, shielding developers from intricate details and promoting a more user-friendly interface. Many companies, like Stripe, heavily promote SDK consumption over their raw APIs.

The challenge in both situations is that the generation of clients and/or SDKs increases in complexity if the underlying APIs are unwieldy or indeed spanning multiple documentation sources. The Workflows Specification specifically targets this challenge by enabling code generation which is driven by actual use cases. It will reduce the bloat experienced by many code generators and prevent consumers from confusion while going off-piste.

Provide consistent and interoperable mechanism for AI model API consumption

As mentioned earlier, the intersection of AI and APIs, will be where much innovation efforts are spent in the coming years. The disruptive power of AI comes in its ability to truly assist humans. For the AI models to carry out meaningful actions upon our request, they need to leverage APIs under the hood.

Interacting with APIs consistently is cumbersome for large language models, mainly down varying levels of quality in APIs and their accompanying reference documentation across the industry.

The question that stands out is: Are we ready for this wave of AI (machine) API consumers? The answer: Not really!

Consequently, we’re seeing a knee-jerk reaction in how providers are augmenting their APIs to work with AI. The lack of standardization in this area means that bespoke semantics per model provider are finding their way into the mindset of designers, developers, and architects. This is a slippery path fraught with interoperability hurdles.

The semantics that work for one set of models, likely will not work well for another, and we risk leaving the human consumers behind. I’m fearful of a new trend in BFLLM (Backend for Large Language Model) API façades being hastily created and forever maintained.

Fortunately, we’re seeing significant interest in how the Workflows Specification can provide a sufficient level of predictable determinism to AI models, allowing them to offer a natural language abstraction on top of the business use cases, while in parallel giving interoperability benefits to the actual API providers. The result is more value, with less vendor lock-in, and consistent API offerings for both humans and the new wave of AI consumers.

Time for an example!


Let’s run through a simple fictitious example of how a company can take advantage of the Workflows Specification We’ll assume the identity of a fictional company called PetCo. 


Problem Statement

We’ve identified a business problem. We’re being overwhelmed by the number of pets being abandoned at our pet store.

Proposed Solution

Following extensive research, we’ve decided to create the capabilities to search for and adopt pets that we catalog. We’ll offer this adoption service through our website and make the APIs available with wider eco-system of pet shelters, pet charities, and pet orphanages who expressed a need for such a service in our research.

Our APIs

Based on our organizational structure, we have set up a new team who will manage the adoption APIs and they are separate to the core Pets catalog facility. Thus, APIs we have on offer are as follows:

  1. Pets API – offering resources and methods required for cataloging pets.
  2. Adoptions API – offering resources and methods to initiate and manage adoptions.

Figure 3 — Example Pets API

Figure 4 — Example Adoptions API

The Workflow

To streamline the understanding and consumption for the wider eco-system of consumers, we want to articulate the process involved in adopting a pet that matches certain criteria.

We’ll leverage the workflows specification to describe the following required steps:

  1. Search for a pet based on certain criteria
  2. Initiate an adoption request
  3. Confirm adoption by updating the adoption status
  4. Verify the adoption has been completed by ensuring the pet catalog entry no longer has the pet tagged as “available”

We can leverage the Workflows Specification structure to articulate the required steps outlined above.

Figure 5 — Showcasing what parts of the Workflows Specification structure is utilized

  1. workflowSpec: 1.0.0 
  2. info:  
  3.   title: A pet adoption workflow 
  4.   summary: This workflow showcases how to search for and adoption a pet from the PetCo `Pet Adoptions API`. 
  5.   description: This workflow walks you through the steps of `searching` for, `selecting`, and `adopting` an available pet. 
  6.   version: 1.0.0 
  7. sourcesDescriptions:  
  8. - name: petsAPI 
  9.   url: 
 10.   type: openapi 
 11. - name: adoptionsAPI 
 12.   url: 
 13.   type: openapi 
 14. workflows: 
 15. - workflowId: FindAndAdoptPet 
 16.   summary: This workflow lays out the steps and API calls needed to search for and adopt a Pet 
 17.   inputs: 
 18.     type: object 
 19.     properties: 
 20.       category: 
 21.         type: string 
 22.       breed: 
 23.         type: string 
 24.       location: 
 25.         type: string 
 26.     required: 
 27.     - apiKey 
 28.     - category 
 29.     - breed 
 30.   steps: 
 31.   - stepId: searchPets 
 32.     description: This step demonstrates the search pets flow for the first pet matching the criteria 
 33.     operationId: petsAPI.getPets 
 34.     parameters: 
 35.     - name: category 
 36.       in: query 
 37.       value: $inputs.category 
 38.     - name: breed 
 39.       in: query 
 40.       value: $inputs.breed 
 41.     - name: location 
 42.       in: query 
 43.       value: $inputs.location 
 44.     - name: status 
 45.       in: query 
 46.       value: available 
 47.     successCriteria: 
 48.     - condition: $response.body 
 49.     - context: $[?length(@.pets) > 0] 
 50.       condition: 
 51.       type: JSONPath 
 52.     outputs: 
 53.       petId: $[0].id 
 54.       petName: $[0].name 
 55.       petLocation: $[0].location 
 56.   - stepId: initiateAdoption 
 57.     description: Initiate an adoption request for an available pet 
 58.     operationId: adoptionsAPI.postAdoption 
 59.     parameters: 
 60.     - name: Authorization 
 61.       in: header 
 62.       value: $inputs.apiKey 
 63.     - name: pet 
 64.       in: body 
 65.       target: $request.body#/pets 
 66.       value: $steps.searchPets.outputs.petId 
 67.     - name: location 
 68.       in: body 
 69.       target: $request.body#/location 
 70.       value: $steps.searchPets.outputs.location 
 71.     successCriteria: 
 72.     - condition: $statusCode == 201 
 73.     outputs: 
 74.       adoptionId: $ 
 75.   - stepId: approveAdoption 
 76.     description: Approve the adoption by sending a PATCH request to the API 
 77.     operationId: adoptionsAPI.patchAdoptionStatus 
 78.     parameters: 
 79.     - name: Authorization 
 80.       in: header 
 81.       value: $inputs.apiKey 
 82.     - name: id 
 83.       in: path 
 84.       value: $steps.initiateAdoption.outputs.adoptionId 
 85.     - name: status 
 86.       in: body 
 87.       target: $request.body#/status 
 88.       value: approved 
 89.     successCriteria: 
 90.     - condition: $statusCode == 200 
 91.     - context: $response.body 
 92.       condition: $.status == "approved" 
 93.       type: JSONPath 
 94.     outputs: 
 95.       status: $response.body.status 
 96.   - stepId: confirmAdoptionStatus 
 97.     description: Confirm the pet status has been marked as adopted 
 98.     operationId: petsAPI.getPetById 
 99.     parameters: 
100.     - name: petId 
101.       in: path 
102.       value: $steps.searchPets.outputs.petId 
103.     successCriteria: 
104.     - condition: $statusCode == 200 
105.     - context: $response.body 
106.       condition: $.status == "adopted" 
107.       type: JSONPath 
108.   outputs: 
109.       petName: $steps.searchPets.outputs.petName 
110.       petId: $steps.searchPets.outputs.petId 
111.       adoptionStatus: $steps.approveAdoption.outputs.status 

Through the power of tooling, it’s then expected that rather than serving the YAML to our consumers, we’d then be able to generate a more human-digestible graphical representation.

api-futures-8-(2).pngFigure 6 — Generating living graphical documentation from a Workflows Specification description

A new major role player

The OpenAPI Workflows Specification is poised to play an important role in the future of API technology. With a rising demand for sophisticated APIs that interconnect across many digital ecosystems, the specification will need to handle intricate scenarios, accommodate emerging technologies (like AI), and aid the application of rigor across many disciplines.

This is why the Workflows Specification is set to be a pivotal tool, adapting to complexities, fostering collaboration, and ensuring secure, efficient API supply chains in the evolving digital landscape. It’s position to evolve in an open and collaborative manner and continue supporting the needs of the industry.

#APIFutures Callout

This blog is part of the inaugural #APIFutures industry event, where thought-leaders and experts across API space. The #APIFutures is a distributed, creator-led effort to identify the most significant opportunities and/or the greatest challenge facing the API community in 2024.

I encourage you to read the other APIFutures articles here.