OpenAPI 月球漫步 2024 - OpenAPI Initiative

一名宇航员在月球上插了一面印有 OpenAPI 标识的旗帜。 OpenAPI 规范的下一步发展是什么？v4 将如何改进 OpenAPI v3 的成功？该规范如何在人工智能和 LLM 的背景下帮助解决问题？

随着 2023 年接近尾声，这些问题的答案开始成型。凭借着在 2024 年底之前 **推出 v4 “月球漫步” 的雄心勃勃的目标**，这将是令人激动的一年。

由于需要完成的工作很多，因此有必要建立一些指导原则。在回顾了去年的大多数提案和讨论之后，这些原则是 **语义**、**签名**、**包容性**、**组织**、**升级**，并且它们的顺序很重要。

1. **🌖 语义提供目的**。仅仅描述 API 的机制是不够的，还需要描述它的语义，无论消费者是人类还是人工智能。语义将 “什么”（… 这是做什么的？）和 “为什么”（… 这有什么关系？）与 “如何”（… 这是如何运作的？）结合起来。
  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 机制。

1. **🌕 包容性需要一个大帐篷**：月球漫步旨在描述所有基于 HTTP 的 API。虽然它在 HTTP API 的设计方面保持中立，但它认识到拥有不同设计风格和观点的重要性。
  月球漫步应该能够描述开发人员可能已经拥有的 HTTP API，以及他们可能想要构建的 API。它应该能够准确地将 API 函数的签名映射到 API 提供的 HTTP 请求和响应的实际实例。月球漫步确实更喜欢资源导向的 API 风格，因为它们非常流行，但它应该能够描述纯粹的 RPC API，即使这些 API 签名是通过 HTTP 标头值或请求正文值来区分的。

1. **🌗 通过关注点分离来组织**。例如，API 的形状变化应该独立于 API 部署。API 部署可以使用不同的安全方案进行保护。API 函数的签名不应该与内容模式格式紧密耦合。
  为了满足不断增长的具有各种需求的客户群，功能数量无疑会增加，从而带来更多复杂性。为了抵消这一点，我们将对 API 描述的不同方面进行更严格的模块化。我们将努力消除目前存在的歧义，并利用现有标准来最大程度地减少不必要的创新。我们的目标是为 API 描述消费者、作者和工具提供商提供更好的体验。

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

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