OpenAPI 满足 SLA - OpenAPI Initiative

这篇文章由 Metadev 创始人兼塞维利亚大学 ISA 集团成员 Pedro J. Molina 博士撰写。.

OpenAPI 中关于 SLA 的特别兴趣小组正在努力创建扩展，以定义 API 的服务级别协议。

该小组的最新工作最近提交给 OpenAPI 技术指导委员会以征求反馈并确保与一般政策保持一致。

SLA4OAI 工作组需要您的帮助，以将这些优势作为 OpenAPI 规范的扩展付诸实践。这篇文章将解释什么是 SLA、它为什么重要以及新的工具如何帮助解决当今所有 API 提供商面临的重要问题。

什么是 SLA？

SLA 是 **服务级别协议** 的简称，它定义了一组关于服务 **可用性**、服务 **质量**（例如最小和最大吞吐量）、**延迟**、**配额**、**速率限制**等的 **指标** 和约束。

此类约束适用于 API 中的特定端点或操作（**资源**）。

这些约束可以可选地组合成多个 **计划**，并且可以具有 **价格**。

Diagram showing SLA as the starting point with branches to a Plan, which decomposes to Pricing, Availability, Rate, and Quota, and a separate path to Metrics and Resource/Endpoint. The paths converge. — SLA 与指标、约束和计划的关系

要解决的问题

API 行业采用 OpenAPI 从非正式的 API 定义转向正式的定义，这些定义可以被人阅读以进行文档记录，也可以被机器用于自动化。

同样，商业 API 通常具有用非正式语言描述的 SLA，这些 SLA 发布在 HTML 页面或 PDF 文档上，机器难以使用。

因此，对标准的需求非常明确，该标准可以帮助描述 SLA。

API 的用例

拥有一个描述 API SLA 的标准格式将能够实现以下用例场景（仅举几例）

SLA 文档：描述限制、速率、配额和预期可用性，以及它们如何应用于不同的端点。
计划和价格说明：解释不同的使用计划和成本。
基于（2）的功能和成本比较：允许根据可用性和质量功能比较替代 API。
SLA 测试工具：检查 API 是否按文档中记录的方式应用了给定的限制。
SLA 衡量：检查指标是否与声明的 SLA 合同一致。
SLA 执行：将配额和限制作为 API 的中间件实施。
SLA 合规性跟踪（全局或按用户）：衡量 API 对 SLA 的实际合规性与理论合规性的程度。
自动计算组合服务的 SLA。可以将多个 API 组合在一起以创建复杂的服务。组合的 SLA 属性可以从简单组件的预期 SLA 推导出来。
轻松在 API 中间件工具中设置 SLA。一些中间件工具提供了实现 SLA 概念的功能，例如指标、限制、配额、速率限制等。拥有一个标准且正式的方式来定义它将简化此类功能的初始配置。

当前规范

经过几个月的努力，特别兴趣小组 (SIG) 达成共识，创建了最小版本 1.0 供人们开始使用并提供反馈。

您可以查看完整的SLA 规范。

早期反馈、路线图和未解决的问题

SLA 定义本身就是一个实体，需要在独立的文档中进行描述，而不是在 OpenAPI 定义中。例如，使用 AsyncAPI 描述的 API 也可能受益于 SLA 描述。

一些开放的设计问题，我们希望社区提供反馈，包括

表示 SLA 信息的最佳方法是什么？目前正在讨论是否应该直接扩展 OpenAPI 文档，或者是否应该将文档分开，然后使用对 API 操作的引用。这可以通过不同的技术来实现，例如嵌入式扩展、补丁/合并机制、覆盖。所有这些都提供了利弊。因此，我们正在评估这里的权衡。
SLA 定义需要引用端点。REST 端点包含 URL 加 HTTP 动词（或者，可以通过 OperationId 引用）。AsyncAPI 操作肯定会有所不同。需要选择一种引用机制来允许指向 OpenAPI、AsyncAPI 或其他 API 中特定 API 操作的指针。
通常，约束和策略应用于一组端点。与其逐一列出所有端点，不如使用基于通配符（*）或正则表达式的机制来简要描述受给定限制影响的所有端点。还建议使用 OpenAPI **标签** 作为应用限制的一种方法。

呼吁实施者

行动的时候到了！

实施者可以开始构建新的令人兴奋的工具来解决当今的问题，这些问题可以将扩展的使用付诸实践，以展示其实用性。SIG 内部也将很快开始这样做，只是为了展示几个使用示例。

因此，如果您有兴趣，请随时询问详细信息并联系 SIG 了解您的实施计划。我们计划维护一个使用 SLA 规范的相关工具列表。

了解更多信息

致谢

感谢所有参与 SLA SIG 的成员：Tim Burks (Google)、Dave O’Neil (Apimetrics)、Paul Cray (Apimetrics)、Hyungjun Lim (Google)、Khushan Adatiya (Google)、Fran Mendez (AsyncAPI)、Emmanuel Paraskakis (独立)、Phil Sturgeon (Stoplight)、Nikhil Kolekar (独立)、Prithpal Bhogill (Google)、Madhurranjan Mohaan (Google)、Isaac Hepworth (前 Google)、Scott Ganyo (Google)、Kin Lane (API Evangelist)、Mike Ralphson (独立)、Jeffrey ErnstFriedman (OpenTravel Alliance)、Antonio Ruiz-Cortes (ISA 集团/塞维利亚大学)、Pedro J. Molina (Metadev & ISA 集团) 和 Pablo Fernandez (ISA 集团/塞维利亚大学)。

还要感谢 TSC 和 OpenAPI Initiative 成员鼓励我们并提供资源和反馈，使这一切成为可能。