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.
.png "api-futures-1-(2).png")
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!
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:
- Pets API – offering resources and methods required for cataloging pets.
- 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:
- Search for a pet based on certain criteria
- Initiate an adoption request
- Confirm adoption by updating the adoption status
- 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: https://api.swaggerhub.com/apis/frank-kilcommins/Pets-API/1.0.0/swagger.json
10. type: openapi
11. - name: adoptionsAPI
12. url: https://api.swaggerhub.com/apis/frank-kilcommins/Adoptions-API/1.0.0/swagger.json
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: $response.body.data.pets[0].id
54. petName: $response.body.data.pets[0].name
55. petLocation: $response.body.data.pets[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: $response.body.id
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.
Figure 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.
