PagerDuty的API开发经验分享 – Increment

banq

在本文中，将分享PagerDuty如何通过很少的新软件开发和一些简单的流程更改来启动的API 开发。
API 契约本质上是一成不变的，添加、更改或迭代它们通常既麻烦又困难。API 更改过程本身可能会令人沮丧和缓慢，并且错误可能会造成极高的代价。但随着产品功能的增长，其 API 也应该增长——因此，拥有明确定义且运行良好的变更流程对企业至关重要。
 
我们着手实现两个简单的目标：
  1. 激励更多 PagerDuty 工程和产品人员关心 API。
  2. 促进我们 API 的创建和维护。
 让更多人做出贡献不仅仅是宣传 API Allies；这是通过简化的工作流程赋予我们的开发人员、产品所有者和技术支持团队权力的一种练习。首先，我们通过 GitHub Actions使用拉取请求模板和内联 linting在我们的模式存储库中广泛使用自动化 。我们还将我们的内部成功和支持团队介绍给了 Stoplight Studio，它是 OpenAPI 模式的 GUI，因此他们甚至无需打开文本编辑器就可以为我们的 API 文档做出贡献。
在几个月的更新过程中，我们听到交付团队的反馈说，发布新的 API 端点令人生畏，因为在 PagerDuty，我们同意一旦发布 API 端点，就不能对其进行重大更改。为了帮助团队更轻松地构建新的 API 端点，我们开发了一个名为 Early Access Framework 的新工具。该工具使团队可以轻松地将他们的 API 标记为早期访问，这让 API 的使用者知道合同可能会发生变化。它还为团队提供有价值的使用数据，以便他们可以迭代他们的设计。
 
随着 API Allies 的顺利启动和运行以及一些轻型工具的到位，我们决定需要专注于发布更多 API。我们希望通过出色的文档和简单的参与流程使团队能够做到这一点。我们着手创建一个轻量级框架，以获取对新 API 添加和更改的评论。我们不希望 API Allies 成为我们 API 的看门人，因此我们设计了框架以推荐但不是必需的。该框架很简单：
  1. 使用我们的API 变更提案模板创建提案。
  2. 通过 Slack 要求 API Allies 对提案进行审查，将分配两名审查人员。
  3. 与指定的审阅者一起完善提案。
  4. 装运它。
自从推出这个推荐的框架以来，我们已经有 10 多个交付团队使用它，只有一个选择不使用。我们相信高注册率是信任交付团队在布局时遵循最佳实践的结果。一个没有使用该框架的团队在设计他们的 API 模式时遇到了问题，从而推迟了他们的项目。
 
我们的架构是在 Swagger 2.0中 定义的，带有用于打包和部署的自定义工具，并以非标准方式托管。对我们内部开发人员来说非常不友好：持续集成工具会不断崩溃，因为它依赖于四个外部依赖项，并且有很多手动部署步骤。升级将通过减少与过时且记录不完整的工具的接触点来最大程度地减少摩擦；它还将使我们的工具与开源社区的其他成员保持一致，从而更容易获得支持。
我们升级到 现代工具，依靠 Stoplight 为我们的文档提供服务，并转向 开源社区。 为了与我们追求简单性保持一致，我们通过将任何冗长的解释移到我们的提案格式、为新开发人员维护常见问题解答文档以及引用外部文档以了解更复杂的概念（如 OpenAPI），从而减少了存储库中的文档数量。我们还使用我们的提案格式记录了我们工具的升级，确保未来的开发人员能够回过头来看看我们做出特定决定的原因。
新工具使我们能够通过三个步骤将更改部署到我们的 API 模式：
  1. 合并到内部存储库中。
  2. 合并到我们的公共架构 存储库中。
  3. 手动更新我们的 Postman 帐户（遗憾的是，此步骤无法自动化）。