随着 2024 年的到来，API 的前景比以往任何时候都更加引人入胜。并非 API 在过去一段时间内失去了任何动力，而是最近人工智能的蓬勃发展使人们的兴趣重新焕发。 人工智能和 API 的交汇点可以说是未来技术创新的核心。
API 的其他热门话题涵盖了 API 即产品运动的进步——这意味着非软件公司提供的 API 将构成其收入流的基本组成部分——以及管理此类产品整个生命周期的挑战变得至关重要。
我们还将看到微服务热潮的平静。随着我们所有人增加我们的数字能力组合，跨多个与 API 相关的行业垂直领域对更好的安全性和更高监管的需求势在必行。
无论公司或行业如何，或者您的技术架构是单体、微服务甚至是微单体，您都需要一个强大的机制来表达和验证您提供的 API 的价值。当您的消费者（无论是人还是人工智能）需要做的不仅仅是单个 API 调用来完成工作时，这一点尤其重要。
让我们明确一点，这种情况几乎占 100%。
此博客是 #APIFutures 的一部分，这是一项由社区主导的协作工作，旨在确定 2024 年 API 经济面临的最大挑战和机遇。如需其他有趣的观点，请查看其他作者在此处列出的文章。
.png "api-futures-1-(2).png")
对工作流的需求以及特殊兴趣小组的成立
在 API 描述的上下文中，您通常希望能够表达特定的调用序列，并阐明它们之间的依赖关系，以实现特定目标。您越快显示此信息，您的消费者就越有可能评估、理解和采用您的产品。
从规范的角度来看，API 行业并没有真正支持该目标，尤其是在现代 API 堆栈中以标准化方式支持该目标。
意识到这一差距促使我们在 OpenAPI 倡议 (OAI) 下成立了一个特殊兴趣小组 (SIG) 来专注于该问题。该工作组确定了几个突出的用例，并且我们过去一年的努力的最终结果催生了新的 API 工作流规范。
随着 OAI 工作组的成立和运作，它已经超越了单一的规范实体，现在有该领域的专家从事整个 API 领域具有广泛相关性的优先主题。激动人心的时刻！
介绍工作流规范
OAI 的工作流规范可帮助您定义和记录工作流——一系列 API 调用——这些调用协同工作以实现特定的业务目标。
图 1 — API 工作流规范结构
该规范可帮助您以人机可读的方式制作工作流。这有助于以更易于开发人员使用的方式解释 API 功能。API 端点可以更快地被理解和使用，从而更容易为传统人类消费者以及新的人工智能消费者实现特定目标。
凭借精心设计的工作流的可断言性质，我们可以解决 API 领域团队面临的许多挑战，并为下一代 API 消费者创造新的可能性。此外，它还提高了监管机构的严谨性。
用例和挑战
以下代表了工作组针对的主要用例集，并且由初始版本的“工作流规范”提供支持。
- 为使用 API 提供确定性配方
- 充当实时文档，并消除对带外 API 文档的依赖
- 为提供商、消费者和监管利益相关者提供可断言的质量
- 增强下一代 API SDK 的生成
- 为人工智能模型与 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 文档、幻灯片、图像等。
这种方法的最大问题是，一旦创建，这些文档很快就会过时，如果它们没有手动更新，就会很快变得不可信。我们设想，围绕工作流规范构建的第一波工具将为用户提供以图形形式呈现规范的能力——不再需要手动创建流程/时序图！
维护 API 文档与其实际实现之间的一致性是工作组深入研究的另一个重大挑战。提供者代码的更改可能并不总是及时反映在文档中，很容易导致不一致。
这可能会使依赖准确文档来有效集成和与 API 交互的开发人员感到困惑。文档和实现之间的一致性至关重要。该领域的大多数行业关注点都集中在确保 API 能够兑现设计所做的承诺，但很少有机制可以确保预期的业务流程仍然可以实现并正确表示，特别是如果该流程跨越多个 API。如果 API 由不同的团队拥有，这种情况会更加困难。
工作流规范充当底层 API 描述之上的外观，并侧重于优先考虑的消费者业务流程。我们相信，该规范为团队提供了一种独特的能力，可以通过将生成的工作流描述用作可断言的动态文档来在其流程中插入更多的严谨性。他们可以验证对底层 API 的扩展和更改是否会破坏预期的用例。
为业务价值提供可断言的机制
要将文档视为动态的，您需要相信它始终是准确的。工作流规范在多个层面上解决了对可断言机制的这种基本需求。
从微观层面来看，它使团队（通过为支持规范而构建的工具）能够验证他们对消费者所做的承诺始终是可以实现的，即使他们通过其 API 产品组合不断发展和交付更改。
从宏观层面来看，工作组正在与监管机构和标准机构合作，这些机构打算利用工作流规范作为应用监管检查和基准测试的机制。
例如，对于开放银行，这将允许各个司法管辖区的监管机构通过针对提供者实施执行可断言的工作流来验证提供者是否满足监管要求。这保证了特定市场的提供者满足了预期要求。
值得注意的是，能够对 API 的预期使用方式进行分类和断言也可能带来安全优势。观察实时 API 使用情况并根据定义的工作流对其进行断言，可以特别管理新的 OWASP Top 10 API 风险中的“无限制访问敏感业务流程”漏洞。
赋能 API 客户端和 SDK 生成器
许多 API 用户依赖代码生成器来引导客户端应用程序的创建并简化他们集成 API 的流程。从提供者的角度来看，许多人更愿意投资于将这种客户端需求提升到一个新的水平，并向消费者公开软件开发工具包 (SDK)，而不是直接访问 API。
SDK 可以通过提供预构建的功能来简化集成，减少开发时间和潜在错误。它可以通过文档、代码示例来改善开发人员体验，并且通常包括用于调试的工具。如果做得好，SDK 可以抽象复杂性，使开发人员免受复杂细节的影响，并促进更友好的用户界面。许多公司（如 Stripe）都在大力推广 SDK 的使用，而不是原始 API。
这两种情况的挑战在于，如果底层 API 难以使用或确实跨越多个文档来源，则客户端和/或 SDK 的生成会变得更加复杂。工作流规范专门针对此挑战，通过支持由实际用例驱动的代码生成。它将减少许多代码生成器所经历的臃肿，并防止消费者在偏离正轨时感到困惑。
为 AI 模型 API 使用提供一致且可互操作的机制
如前所述，AI 和 API 的交叉点将是未来几年投入大量创新努力的地方。AI 的颠覆性力量在于它能够真正帮助人类。为了让 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 文章.
