API工作流的概念已成熟，并由OpenAPI Initiative推出了一项新规范，名为Arazzo规范。虽然以下博客为该规范提供了一些有用的背景信息，但我们鼓励您查阅我们最新的博客——“Arazzo规范——深度解析”
随着2024年势头强劲，API的前景比以往任何时候都更加引人入胜。并非API在过去一段时间内失去了任何势头，而是最近人工智能的蓬勃发展重新激发了人们的兴趣。人工智能与API的结合可以说是未来技术创新的核心。
API的其他热门话题包括“API即产品”运动的进展——这意味着非软件公司提供的API将成为其收入来源的重要组成部分——以及管理此类产品的完整生命周期的挑战变得至关重要。
我们还将看到微服务热潮的平息。随着我们数字能力的组合不断增加，在许多涉及API的垂直行业中，对更强安全性和更严格监管的需求变得势在必行。
无论公司或行业，也无论您的技术架构是单体、微服务，甚至是微型单体，您都需要一个强大的机制来表达和验证您所提供的API的价值。当您的消费者（无论是人类还是AI）需要通过不止一次API调用来完成工作时，这一点尤为重要。
坦率地说，这种情况几乎百分之百发生。
本博客是#APIFutures的一部分，这是一项由社区主导的协作努力，旨在识别2024年API经济面临的主要挑战和机遇。要了解其他有趣的观点，请查阅此处列出的其他作者的文章。
.png "api-futures-1-(2).png")
对工作流的需求和特别兴趣小组的成立
在API描述的语境中，您通常希望能够表达特定的调用序列，并阐明它们之间的依赖关系以实现特定目标。您越快地呈现这些信息，您的消费者就越有可能评估、理解和采纳您的产品。
从规范的角度来看，API行业尚未真正支持这一目标，尤其是在现代API堆栈中缺乏标准化方式。
意识到这一差距促使我们在OpenAPI Initiative (OAI) 下成立了一个特别兴趣小组 (SIG)，以专注于解决此问题。该工作组确定了几个突出的用例，我们过去一年努力的最终成果催生了一个新的API工作流规范。
随着OAI工作组的成立和运作，它已超越单一规范实体的范畴，现在拥有领域专家就API领域广泛相关的重要议题开展工作。令人兴奋的时代！
介绍工作流规范
OAI的工作流规范可帮助您定义和文档化工作流——一系列API调用——它们协同工作以实现特定的业务目标。
图1 — API工作流规范结构
该规范帮助您以人类可读和机器可读的方式创建工作流。这有助于以一种对开发者而言更易于使用的方式解释API功能。API端点能够更快地被理解和使用，从而使传统人类消费者以及新一代AI消费者更容易实现特定目标。
凭借所创建工作流的可断言性，我们可以应对API领域团队面临的诸多挑战，并为下一代API消费者创造新的可能性。此外，它还提高了监管机构的严谨性。
用例与挑战
以下代表了工作组针对并由工作流规范初始版本所满足的主要用例集。
- 提供使用API的确定性“食谱”
- 作为活文档，消除对带外API文档的依赖
- 为提供者、消费者和监管利益相关者提供可断言的特性
- 赋能下一波API SDK生成
- 为AI模型与API交互提供一致且可互操作的机制
提供使用API的确定性“食谱”
团队需要组织其API端点，使其对消费者易于理解。在单体架构方法中，API描述（例如OpenAPI描述）变得笨重并包含数十甚至数百个端点是很常见的。
另一方面，如果结构过于模块化，那么大多数消费者用例将需要与多个API描述进行交互。
图2 – 交付质量与预期之间的差距一致性 - SmartBear SOSQ API 2023年报告
在这两种情况下，都必须向消费者阐明预期的消费流程，并确保API采用者清晰地了解业务价值。使用现有的规范是有益的，但行业仍然不确定（参见图2）它们是否提供了预期的开发者体验。
这是工作流规范的亮点之一。它超越了API描述的典型限制，探索了如何协调一致地编排众多API端点，无论它们是否分散在多个描述文件中。它可以用于描述包含许多API调用的复杂流程，使事物清晰有序地满足消费者需求。
当API是更大系统的一部分时，这一点很重要。工作流规范允许团队清晰地定义交互，确保API流程易于预测、处理和扩展。这种特性让提供者能够描述所提供的特定用例，以解决消费者挑战，无论其端点分组策略如何。
作为API的活文档
技术参考文档，如OpenAPI描述，仅是消费者API文档需求的一部分。实际上，优秀的API文档由多种类型的文档组成——参考、概念、任务。即使在2024年，我们仍然必须依赖手动创建的工件来解决我们的API所涵盖的概念，以及为从中提取价值而需要执行的任务。
表达这些文档类型的主要媒介仍然是静态形式——例如开发者门户页面内的HTML或Markdown内容。更糟糕的是，它们经常以完全带外的方式共享，使用更易于人类阅读的格式，如PDF、MS Word、Google Docs、幻灯片、图片等。
这种方法最大的问题是，一旦创建，这些工件很快就会过时，如果它们不手动更新，就会很快变得不可信。我们设想，围绕工作流规范构建的第一波工具将提供以图形形式向消费者呈现规范的能力——不再需要手动创建流程/序列图！
维护API文档与其实际实现之间的一致性是工作组深入探讨的另一个重大挑战。提供者代码的更改可能不会总是及时反映在文档中，很容易导致不一致。
这可能会让依赖准确文档来有效集成和交互API的开发者感到困惑。文档与实现之间的一致性至关重要。该领域的大部分行业关注点在于确保API能够兑现设计所作的承诺，但很少有机制能确保预期的业务流程仍然可以实现并正确表示，特别是当该流程跨越多个API时。如果API由不同的团队拥有，这将变得更加困难。
工作流规范充当底层API描述之上的一个门面，并专注于优先级高的消费者业务流程。我们相信，该规范为团队提供了一种独特的能力，可以通过利用生成的工作流描述作为可断言的活文档，在其流程中注入更多严谨性。他们可以验证对底层API的扩展和更改不会破坏预期的用例。
提供业务价值的可断言机制
要将文档视为活文档，您需要信任它始终是准确的。工作流规范从多个层面解决了对可断言机制的这一基本需求。
从微观层面来看，它赋能团队（通过支持该规范的工具），验证他们对消费者做出的承诺始终可以实现，即使他们通过其API组合进行演进和交付变更。
在宏观层面，工作组正在与监管和标准机构合作，这些机构打算利用工作流规范作为应用监管检查和基准测试的机制。
例如，对于开放银行，这将允许各司法管辖区的监管机构通过对提供商实施可断言的工作流来验证提供商是否符合监管要求。这确保了提供商针对特定市场满足了预期要求。
值得注意的是，能够分类和断言API预期“如何”被消费也可能带来安全效益。观察实时API消费并根据已定义的工作流进行断言，可以具体管理对敏感业务流的无限制访问漏洞，该漏洞是API新版OWASP十大风险的一部分。
赋能API客户端和SDK生成器
许多API消费者依赖代码生成器来引导客户端应用程序的创建，并简化其API集成过程。从提供商的角度来看，许多人更愿意投入精力将这种客户端需求提升到新的水平，并向消费者公开软件开发工具包（SDK），而不是直接API访问。
SDK可以通过提供预构建函数来简化集成，减少开发时间和潜在错误。它可以通过文档、代码示例来改善开发者体验，并且通常包含调试工具。如果做得好，SDK可以抽象复杂性，保护开发者免受复杂细节的困扰，并推广更用户友好的界面。许多公司，如Stripe，都大力推广SDK的使用而非其原始API。
在这两种情况下，挑战在于如果底层API过于庞大或确实跨越多个文档来源，客户端和/或SDK的生成会变得更加复杂。工作流规范通过支持由实际用例驱动的代码生成来专门解决这一挑战。它将减少许多代码生成器所经历的冗余，并防止消费者在脱离预设路径时感到困惑。
为AI模型API消费提供一致且可互操作的机制
如前所述，人工智能与API的交叉点将是未来几年大部分创新投入的领域。人工智能的颠覆性力量在于它能够真正协助人类。为了让AI模型根据我们的请求执行有意义的操作，它们需要在底层利用API。
对于大型语言模型而言，始终如一地与API交互是很麻烦的，这主要是因为行业内API及其附带参考文档的质量水平参差不齐。
突出的问题是：我们是否为这波AI（机器）API消费者做好了准备？答案：并没有！
因此，我们看到提供商在如何增强其API以与AI协同工作方面出现了条件反射式的反应。该领域缺乏标准化意味着每个模型提供商的定制语义正在进入设计师、开发者和架构师的思维模式。这是一条充满互操作性障碍的崎岖之路。
适用于一套模型的语义很可能不适用于另一套模型，我们有将人类消费者抛在身后的风险。我担心BFLLM（大型语言模型后端）API门面仓促创建并永久维护的新趋势。
幸运的是，我们看到人们对工作流规范如何为AI模型提供足够的可预测确定性表现出浓厚兴趣，使其能够在业务用例之上提供自然语言抽象，同时为实际的API提供商带来互操作性优势。结果是价值更高，供应商锁定更少，并且为人类和新一代AI消费者提供一致的API产品。
是时候举个例子了！
示例
让我们来看一个简单的虚构示例，了解公司如何利用工作流规范。我们将假设一家名为PetCo的虚构公司的身份。
问题陈述
我们发现了一个业务问题。我们正被宠物店里被遗弃的宠物数量所困扰。
拟议解决方案
经过广泛研究，我们决定创建能够搜索和领养我们编目宠物的能力。我们将通过网站提供这项领养服务，并将API提供给更广泛的宠物收容所、宠物慈善机构和宠物孤儿院，这些机构在我们的研究中表达了对这项服务的需求。
我们的API
根据我们的组织结构，我们成立了一个新团队，负责管理领养API，他们与核心宠物目录设施是独立的。因此，我们提供的API如下：
- 宠物API——提供宠物编目所需的资源和方法。
- 领养API——提供发起和管理领养所需的资源和方法。
图3 — 宠物API示例
图4 — 领养API示例
工作流
为了简化更广泛消费者生态系统的理解和使用，我们希望阐明领养符合特定条件的宠物所涉及的流程。
我们将利用工作流规范来描述以下所需步骤：
- 根据特定条件搜索宠物
- 发起领养请求
- 通过更新领养状态确认领养
- 通过确保宠物目录条目不再将宠物标记为“可用”来验证领养是否已完成
我们可以利用工作流规范结构来阐明上述所需步骤。
图5 — 展示工作流规范结构中被利用的部分
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
借助工具的力量，我们预期届时将能够生成更易于人类理解的图形表示，而非直接向消费者提供YAML。
图6 — 从工作流规范描述生成活的图形文档
一个新的主要参与者
OpenAPI工作流规范有望在API技术的未来中发挥重要作用。随着对互联互通于众多数字生态系统的复杂API的需求不断增长，该规范将需要处理复杂场景、适应新兴技术（如AI），并帮助在许多学科中应用严谨性。
这就是为什么工作流规范将成为一个关键工具，它能适应复杂性、促进协作，并确保在不断发展的数字环境中实现安全高效的API供应链。它将以开放和协作的方式发展，并继续支持行业需求。
#APIFutures 倡议
本博客是首届#APIFutures行业活动的一部分，该活动汇集了API领域的思想领袖和专家。#APIFutures是一项分布式、由创作者主导的努力，旨在识别2024年API社区面临的最重要机遇和/或最大挑战。
我鼓励您阅读此处的其他APIFutures文章.
