Marsh Gardiner

OpenAPI 规范的下一步是什么？v4 如何改进 OpenAPI v3 的成功？规范如何在 AI 和 LLM 的背景下帮助解决问题？

随着 2023 年的结束，这些问题的答案开始成形。随着在 2024 年底发布 v4 “月球漫步”的积极目标，这将是激动人心的一年。

由于有许多工作要做，因此有必要制定一些指导原则。在回顾了去年提出的主要提案和讨论后，这些原则是语义、签名、包容性、组织、升级，它们的顺序很重要

1. 1. 🌖 语义提供目的。仅仅描述 API 的机制而不描述其语义是不够的，无论消费者是人类还是 AI。语义将“什么”（… 这是做什么的？）和“为什么”（… 这为什么重要？）与“如何”（… 这是如何工作的？）联系起来。

      OpenAPI 帮助人们更快地构建更好的 API，并且工具生态系统年复一年地提供更多价值。今天在 2023 年的新事物是新类型 API 消费者的兴起——生成式 AI。LLM 可以处理 OpenAPI 描述，然后使用该 API 来解决问题。随着生成式 AI 理解自然语言的能力，OpenAPI 可以帮助非开发者以以前从未见过的可访问性水平利用 API 的力量。为了充分实现这种潜力，API 生产者应该用传达这些 API 操作的含义和目的的细节来装饰他们对 HTTP 请求的机械描述。反过来，这也有助于人和 LLM 获得更好的结果。

      换句话说，人们几个世纪以来一直在使用柔软的自然语言彼此交流，我们几十年来一直在使用脆脆的编程语言与机器交流。LLM 连接了柔软和脆脆的世界，这意味着之前无法使用 API 的大量人现在可以使用 API 了。

      无论您对生成式 AI 的看法如何，从过度炒作到改变世界，我们都可以预期许多人将使用 OpenAPI 来驱动基于 AI 的 API 消费者。如果 OpenAPI 没有努力满足该社区的需求，他们就会找到替代方案。

   2. 🌒 请出示签名！ API 代表一组函数，每个函数都描述了面向客户端的目的。函数可以通过其签名来识别，该签名与一组 HTTP 交互相关。月球漫步将此概念置于其中心。

      任何 HTTP API 都是为了达到某个目的。API 消费者更喜欢重用现有功能，理想情况下，他们可以用最适合他们的方式了解该功能。PUT/PATCH/DELETE 返回 200 或 204 是一个实现细节，与它为客户端执行的功能相比，它相形见绌。如今，在 OpenAPI 中表达 API 函数签名的途径有限。pathItem 无法使用查询参数来区分操作。每个 HTTP 方法只能有一个操作。由于缺乏对唯一签名的正式定义，这些是对 API 函数签名的人为约束。OpenAPI 过去的工作重点是使开发人员能够描述 HTTP API。这使它们重新排序，以便开发人员可以使用 OpenAPI 来定义具有唯一签名的 API 函数，然后将每个签名映射到 HTTP 机制。

3. 3. 🌕 包容性需要一个大帐篷：月球漫步旨在描述所有基于 HTTP 的 API。虽然它对 HTTP API 的设计方面保持中立，但它认识到拥有不同设计风格和意见的重要性。

      月球漫步应该能够描述开发人员可能已经拥有的 HTTP API，以及设计他们可能想构建的 API。它应该能够准确地将 API 函数的签名映射到 API 提供的 HTTP 请求和响应的实际实例。月球漫步确实更喜欢面向资源的 API 风格，因为它们非常流行，但它应该能够描述纯粹的 RPC API，即使这些 API 签名是通过 HTTP 标头值或请求正文值来区分的。

4. 4. 🌗 通过关注点分离实现组织。例如，API 的不断变化的形状应该独立于 API 部署。API 部署可以使用不同的安全方案进行保护。API 函数的签名不应与内容模式格式紧密耦合。

      为了支持具有不同需求的不断增长的客户群，功能数量无疑会增长，从而带来更多复杂性。为了抵消这一点，我们将对 API 描述的不同方面的模块化应用更多严格性。我们将努力消除目前存在的歧义，并利用现有标准来最大程度地减少不必要的创新。我们的目标是为 API 描述消费者、作者和工具提供者提供更好的体验。

5. 5. 🌑 机械升级。OpenAPI v3 的一个重要原则是它提供了从 v2 直接升级的路径。月球漫步继承了这一原则，这意味着它必须再次能够从 v3（以及扩展的 v2）机械地升级到月球漫步。

像 OpenAPI 这样的重要开源项目依赖于许多人的贡献。如果您像我们一样对上述想法或利用 AI 帮助更多人使用 API 的机会感到兴奋，那么请参与进来！一个很好的开始方法是加入我们每周四的电话会议（详细信息），任何想加入的人都可以！