轻量级 API 治理是开发新 API 的一种根本性变革，它可以提高开发人员的幸福感，降低成本并加快上市时间。

译自 API Governance and Developer Experience in a Developer Portal，作者 Aidan O'Connor。

企业通常会转向 API 目录，以提高 API的可发现性并降低重复业务逻辑的风险。然而，虽然目录可以相对轻松地公开所有可用的内部 API，但它无法满足开发者体验的转型需求。

在考虑如何改进与构建新 API 相关的当前开发者流程时，他们应该考虑以下三个问题（最初由 Platformable 的 Mark Boyd 在 Portal Talks 2024中提出）：

  • 开发者是否感到满意？

他们对自己的工作感兴趣吗？他们是否高效、解决问题并构建事物？还是他们参与了手动重复的任务？

  • 成本是否降低？

与重复性任务相关的劳动力成本是否很高？容易避免的错误、错误配置和漏洞是否会不必要地占用本应用于深度专注的时间？这是否会增加客户获取成本？

  • 上市时间是否很快？

企业能否以最快的速度创建产品和服务，并从新的收入来源中获利？

Boyd 建议采用轻量级 API 治理来改进（如果不是完全改变）开发新 API 时的开发者体验。这种方法概述了开发新 API 方式的根本性变化，提高了开发者满意度，降低了成本，并加快了上市时间。

内部开发者门户中的轻量级 API 治理

让我们探讨如何在 内部开发者门户中使用轻量级 API 治理，以及为什么要这样做：

规划

上下文为开发者提供先机

当工程团队确定 API 用户需要某些东西时——无论是新的 API 还是现有 API 中的附加功能——并且解决方案架构师确认满足此需求的最佳方法是 API 时，规划过程应使用 API 目录进行信息化。没有 门户可以取代工程组织中宝贵的遗留知识，但使用门户可以引导开发者走上正确的道路。

例如，与其询问团队中最资深的开发者，“您知道是否存在执行 <业务功能> 的 API 吗？如果是，谁拥有它？”，您应该首先参考门户中托管的全局 API 目录，然后熟悉 API，然后联系技术负责人或主题专家以填补空白。

开发者可以使用门户来了解 API 的功能、API 的健康状况、已实施的速率限制以及其他重要的测试注意事项。此外，开发者可以使用 自助服务操作在他们选择的门户中对 API 进行评分（一到五颗星，可以选择添加评论）。这使工程领导能够推广高评分的 API，并对低评分的 API 提供具体反馈。结合这些具体示例，开发者在使用其他 API 之前可以获得先机。

自助服务操作允许开发者在 DevOps 或安全团队确定的护栏内，通过点击按钮执行必要的操作，从而无需使用影响生产力的工单。

 

开发者可以在门户中查看有关 API 的信息。

考虑标准

您可以 尽早让产品经理参与进来——如果您正在开发仅为您的业务部门服务的 API，这很容易，但如果您的 API 超出了您的团队控制范围的虚拟边界，则难度更大。在门户中积极记录产品经理、他们的 标准和他们的路线图可以支持这项工作。

如果您的工程团队仅仅依靠维基来概述 API 开发标准，但维基的所有权不明确，开发人员可能会因为试图做正确的事情而感到沮丧，结果却被告知文档已经过时。最佳方法通常不是在维基中记录分步指南，而是将这些说明转换为简短的自助操作，使开发人员能够提供最少的输入并获得他们所需的确切内容。在这种情况下，维基最适合用于对方法的主观描述，而不是任务列表。下图显示了这可能看起来的一个示例，但请记住，所有输入都是可自定义的，并且可以使用高级配置。

 

门户中的自助服务表单为开发人员提供了在 API 方面的自主权。

使用多种 API 设计工具的组织应确保开发人员不必猜测哪种工具最适合手头的任务，或者在自助服务操作中向开发人员提出几个问题，以自动引导他们使用正确的设计工具。同样，它将通过要求他们填充模板来指导他们编写规范，而不是让他们自己寻找合适的模板。

计划新 API 的开发人员可能需要咨询另一个业务部门，以确定如何最好地融入其数据模型。您可以通过确保特定团队的数据模型在门户的团队页面上准确地描述出来，来加快这种协作。

在开发这个新的 API 时，开发人员应该首先检查门户以了解潜在的 API 消费者角色，并查看任何现有的功能请求以及 API 分析，以支持他们关于 v1 中应该包含哪些内容的决策。在内部协作工具（如 Slack 或 Teams）中搜索、进行数据调用以获取最新的 API 需求或查看过时的电子表格可能会导致开发错误的功能。使用 维护最新开放功能请求的门户并将 API 分析提炼成可用于决策的见解，可能是更好的方法。

为了结束规划过程，Boyd 建议编写一份新闻稿，向全世界宣布开发人员将从这个新的 API 中获得的新的价值。这可能是引导开发人员在被指向正确的工具后规划其 API 的自助服务操作的最后一步。同样，利用门户中存储的有关 API 消费者的信息，通过使用自助服务操作直接从门户向合适的潜在用户广播公告，可能是有益的。公共公告渠道有时会被忽略，但可以手动或自动选择针对特定受众的渠道，以确保公告发送到合适的受众。

 

黄金路径

当开发人员使用来自过时文档的错误模板或寻求他们的帮助来完成文档不足的简单任务时，DevOps 团队经常感到痛苦。同时，开发人员也面临着需要找到正确的文档页面、通过创建一系列相互关联的票证来执行所有必要步骤，然后几天后再次回来发现问题已经完全阻止了整个过程。

另一种方法是将文档转换为自动化形式，并为 API 开发人员提供 黄金路径。这确保了开发人员能够立即获得他们需要的东西，并确保标准得到维护。

Boyd 描述了应该包含在单个自助服务操作中的几个关键要素：

  • 一个包含关键资源和配置的存储库模板，使开发人员能够在代码开发最佳实践的护栏内快速入门。
  • 一个可以构建此存储库并将生成的工件一直推送到生产环境的管道。这应该包括组织信任部署到生产环境的代码所需的所有步骤。
  • 一组清单，允许部署此应用程序。例如：Helm 图表、Kustomize 配置或其他非 Kubernetes 配置。 可观察性内置。日志、跟踪、指标和警报的合理默认值，可以根据需要进行调整，但需要开发人员最少的思考和输入。

除了使用自助服务操作创建新 API 外，门户还可以用于“ 第 2 天操作，”即修改现有实体的操作。一些示例包括将 API 部署到 API 网关或丰富遗留 API 的信息，而无需将元数据模板复制粘贴到存储库中。

 

门户中第 2 天操作的快速操作示例。

所有权和协作

上面描述的黄金路径应自动选择 API 的所有权。如果 API 具有上游或下游 API 依赖项，则应由启动黄金路径的开发人员自动推断或轻松声明，并且应根据这些声明的依赖项自动推断协作团队网络。

DevSecOps 内置，而非附加

拥有新 API 的开发人员在最关键的时间寻求 DevSecOps 的批准：在部署到生产环境之前。DevSecOps 团队明白他们的职责是服务于组织的业务目的，但往往会被善意的 API 开发人员置于这种困境中，这些开发人员试图为他们的 API 做最后的润色。DevSecOps 可以快速工作，但往往不够快。

要解决这个问题，需要流程变更和工具变更。DevSecOps 应该参与 API 开发过程。他们的一些辛勤工作应该体现在上面描述的黄金路径中，其中新 API 从一开始就符合要求，因为默认管道中包含安全步骤。

默认管道和与 DevSecOps 的讨论并不能解决所有安全和监管问题，因此可以使用门户中的记分卡自动跟踪和执行 API 的客观安全和监管标准。DevSecOps 团队可以审查正在开发的 API 的记分卡，如果满足他们的标准，则 API 可以进入生产环境，而无需 DevSecOps 的主动直接参与。这就是工程副总裁梦寐以求的：一条满足所有需求的快速进入生产环境的途径。

处理敏感数据（如 PII 或 PHI）的 API 也可以从自定义属性（如“处理的数据类型”）和仅适用于这些 API 的记分卡中受益，确保无缝部署到生产环境，帮助工程和 DevSecOps。

默认情况下为 InnerSource

拥有不同开发团队的组织担心重复工作会不必要地减缓开发速度。为了防止这种情况，组织试图实施 InnerSource 程序。如果没有一种方法来强制执行此程序（一个自定义构建的存储库扫描器，或者更好的是，一个具有 InnerSource 批准的黄金路径和记分卡的门户），InnerSource 程序往往是工程团队事后才想到的。

虽然开发人员可能反对新的 InnerSource 要求（例如，存储库更改，如包含详细的 GETTINGSTARTED.md、CONTRIBUTING.md 或 HELPWANTED.md 文件），但当被要求开发已经构建的 API 或被要求开发组织中其他人已经解决的复杂功能时，他们将收获这些要求的好处。自动摄取这些文件（当然还有 README.md 和其他文档）会使它们成为 Port 中全局搜索功能的一部分。当与“主题专家”或“技术负责人”等可定制字段配对时，开发人员能够快速找到他们想要的东西，并通过提出正确的问题与合适的同事进行协作。

“求助”市场和“即将开展的工作”日历

Boyd 指出，最适合与 API 一起使用的门户还包括一个即将开展的工作日历，开发人员可以从不同的团队查看其他团队的计划工作。除此之外，组织有时需要一个“求助”和“提供帮助”的市场，工程团队负责人可以在其中借用和借出帮助，以确保他们自己和组织的开发需求得到满足。

最后润色

最后，有些工具只在 API 开发过程的后期发挥作用，包括 linter 和 API 风格强制工具。将这些工具向左移动可能会有好处，但有一个自助服务操作来将 API 暂存到生产环境中，从而引入这套最终工具集，将加快上市时间，并在流程结束时加快速度。

结论

回到开发 API 时应该指导增强开发人员体验的三个问题：

  • 开发人员是否满意？
  • 成本是否降低？
  • 上市时间是否快？

门户在确保每个问题的答案都是响亮的“是”方面发挥着关键作用。自助操作是让开发人员专注于构建事物和解决问题的黄金路径，在很大程度上减轻了他们手动重复任务的负担。记分卡经常早早地缓解了 DevSecOps 和 GRC 团队的担忧，提供对开发中 API 的客观检查，确保审批成本（在花费在手动检查上的时间方面）很低。API 目录确保开发人员以快速的速度交付 API，通过加快发现现有 API 和协作的速度来缩短上市时间。

本文在 云云众生（ https://yylives.cc/）首发，欢迎大家访问。