设计API：如何看待公共API

定义问题

所有软件项目都受益于从客户及其正在从事的工作或他们遇到的问题开始。API 设计以同样的方式开始：您需要首先清楚地说明您要帮助谁以及您将如何帮助他们。

在这种情况下，我们知道我们的客户经常手动导出他们的项目文件，我们从他们中的许多人那里听说他们希望自动化此过程。通过客户访谈和早期 beta 测试人员，我们了解到客户特别希望在下游工具中利用他们的 OAS 和 JSON Schema 文件，并且通常将其作为 CI/CD 管道的一部分。

Stoplight 的流程包括为任何重大计划创建“项目章程”，以便我们能够努力实现完美协调。作为 API 项目，此章程包含一些特定于 API 的类别，但其他方面与任何其他项目一样。它包括：

高级目标，包括客户目标（自动导出）、业务目标（通过有用的集成进行保留）和技术目标（创建基础以更轻松地构建未来的 Stoplight API）
特定客户请求、用例和边缘情况
需求细分，包括专注于令牌生成、身份验证、速率限制和停用、分析、调试工具、性能预期以及定价和包装的用户故事
UI 模拟
利益相关者、销售和客户成功常见问题解答
发布策略
测试说明

我对 API 产品经理的建议是：在进入 Stoplight之前做好这项工作。一旦你有了章程的初稿，就谦虚地向尽可能广泛的受众征求积极的反馈，包括工程师、主题专家、销售、支持、QA、UX 和热切的客户。在对总体目标和预期的开发人员体验 (DX) 充满信心之后，你就可以开始在 OpenAPI 中构建 API 端点和各种模型。

设计解决方案

Stoplight 的客户来自不同的行业，从小型企业到大型企业都有。一些客户拥有强大的 API 程序和完善的质量控制，而其他客户则刚刚开始他们的 API 之旅。我们立即意识到，Catalog API 需要可靠（这意味着高性能和容错性）和易于使用（这意味着利用行业标准）才能吸引人们采用。

可靠性

首先，API 需要可访问且安全。我们探索了多种机制来实现这一点，包括细粒度权限、个人访问令牌、基于 JWT 的解决方案、oauth2 流程等。经过讨论，我们最终选择了所谓的工作区令牌。这些承载令牌由所有者创建，具有明确的只读访问权限，永不过期，并且不附加到特定用户。我们认为这在可用性和安全性之间取得了良好的平衡，但最终我们希望为您构建一些有用的东西。

与任何其他产品一样，API 也在不断发展。与典型的 Web 应用程序不同，API 无法拥有能够直观地适应新功能和迭代的人工控制者。相反，API 需要在第一天就采用版本控制策略。通过让客户能够将其集成固定到 API 的特定版本，他们可以确信重大更改不会停止他们的管道。Stoplight 更喜欢简单的基于日期的版本控制机制。Catalog API 的首个版本是 `2023-07-12`。

现在，导出不再需要手动点击按钮，我们需要确保底层导出引擎能够承受额外的流量。我们借此机会重构了一些长期沉寂的“龙”，并添加了更多用于监控和调试的遥测数据。

由于性能是成功的关键指标，并且导出引擎经过了翻新，我们希望逐步全面地测试我们的系统。我们首先在 UI 中添加了一个新的导出选项（如果出现问题，客户可以禁用该选项）以开始产生流量。为了帮助我们识别极端情况，我们将导出指向“最全面、符合标准和最新的机器可读 API 定义目录”（可在此处获得： https: //github.com/APIs-guru/openapi-directory），并对原始文档和我们的新导出运行了频谱。在许多情况下，我们发现使用新导出时验证错误的数量显著减少。在大多数情况下，这是清理 x-examples 和其他从 OAS2.0 更改为 OAS3.X 的属性的结果。

便于使用

由于我们客户的目标是提取完整且有效的定义文件（OAS 和 JSON Schema）并将其集成到下游工具中，因此 Catalog API 需要提供完全独立的“捆绑”导出，无需外部引用或依赖项。Catalog API 不是简单地内联取消引用 $refs，而是创建可重复使用的“组件”（适用于 OAS3.X）或“定义”（适用于 OAS2）。这保留了各种工具（例如 SDK 生成）中使用的重要参数和模型名称。

（左侧为原始组件库参考，右侧为捆绑导出）

与 API 身份验证和版本控制类似，还有一些其他“基础”设计决策：

标准化错误模型– 我们采用了RFC7807。但是，我了解到，最好为不同的错误情况创建不同的模型，即使它们具有相同的属性，因为这些模型将由 SDK 生成器使用。
速率限制– 保护您自己的系统并为您的客户提供限制自身速率所需的信息。常用的 x-rate-limit、x-rate-limit-remaining 和 x-rate-limit-reset 可以完成这项工作。
请求标识符– 您、您的支持团队和工程师都会感激简单的 Stoplight-Request-Id响应标头所提供的附加上下文。将此标识符包含在所有相关日志中，并培训您的客户将其包含在您的支持请求中，以使调试变得轻而易举。

在设计阶段，您可能会花费最多时间充实端点。由于 Stoplight 本身是围绕项目及其内容组织的，因此我们首先将 /projects/ 作为主要资源。指定分支（对于 Web 项目，也称为“版本”）或提交是必要的子资源，最后使用 /export/ 命令，后跟要导出的目标的文件路径。可选地，有一个 include_internal 查询字符串参数，它将包含或排除标有 x-internal 的对象（默认为 true）。我们相信最终结果直观且易于缓存。