译自：API Governance: Using Patterns From PayPal, Netflix and More 作者：Charles Humble
许多组织将API治理交给机会，但这是一种冒险的做法。相反，看看全球企业如何指导他们的API开发。
我承认，API 治理并不是一个令人心跳加速的话题。它或许最好被描述为枯燥但重要。
做好 API 治理，有助于保持一致性并促进 API 的重用。它还应该提供一种机制，让内部和外部客户都能提供反馈并请求更改。然后，可以根据其他竞争性优先事项评估这些请求，以便就是否、如何以及何时实施它们做出决策。
根据我的经验，许多组织将 API 治理 交给机会。但是，与组织文化一样，无论你是否定义治理流程，它都会出现。因此，在我看来，最好是有意为之。
治理不必繁琐。许多开发人员都欢迎有关如何设计 API 的指南，因为这意味着不必过多地担心做出选择——例如如何处理一组 API 结果中的分页，或者事务 ID 应该叫什么。
INNOQ 的首席顾问、O'Reilly 作者和 API 建议 YouTuber Erik Wilde 告诉 The New Stack：“在最近德国的一次会议上，我问了 150 名开发人员，‘你们有多少人在组织中拥有 API 指南？’，只有很少的人举手。”“然后我问，‘你们有多少人希望拥有指南？’，看起来大多数人都举手了。我没有预料到差异会如此之大。”
如果你想为组织中的 API 建立治理流程，你可以应用三种主要模式：集中式设计权限、联邦式治理和受影响的自治理。每种模式都有不同的权衡，并且更适合某些情况。
在本文中，借助现实世界的例子，我们将研究每一种模式，并检查它最适合应用于何处。
集中式设计权限 (CDA) 带有架构审查委员会和过于官僚的流程的包袱，或许是我们考虑的三种模式中最不受欢迎的一种。但这不应该让你忽视这样一个事实：在某些情况下，它可能是有效的。
例如，它是发展编程语言的一种广泛采用的方法——想想 C++ 的 ISO 标准、Java 的 Java 社区流程 或 Python 增强提案 (PEP) 流程以及相应的 Python 指导委员会。
CDA 的主要作用是看门人，这意味着为了有效，它需要防止做出低质量或有风险的决策。除了其看门人的作用外，该机构还应验证良好的决策，并通过 文档 和其他指导来告知团队如何满足质量要求。
投资高质量文档尤其重要；如果没有它，实施团队需要与 CDA 举行的会议数量会迅速膨胀到无法管理的程度。
由于 CDA 的主要作用是看门人，因此其成功在很大程度上受到组织内技术团队文化的的影响。如果各个团队觉得可以忽略 CDA 告诉他们做的事情，那么它就无法有效。相反，CDA 需要认识到，过于繁重或官僚的流程会促使开发人员寻求绕过它的方法。
使用 CDA 模式的主要优点是它推动了统一性。使用此模式可以避免或至少限制开发人员拥有更多自主权时可能发生的重复工作量。它还可以确保正确遵循安全策略和其他组织协议。
一个重要的缺点是，随着公司的发展，该机构几乎不可避免地会成为瓶颈，导致 API 项目停滞不前，因为其成员等待与核心团队讨论问题。
Wilde 建议：“使用此模型，你通常会遇到可扩展性问题，开发人员认为设计权限阻碍了他们的工作。”“这与其说他们不喜欢该机构正在做什么，不如说他们认为这会减慢他们的速度，因此他们试图绕过它来完成工作。” 与其他形式的软件架构权威一样，API 设计权威成员也存在与实际工作脱节而无法做出良好决策的风险。这种现象等同于Stack Overflow的共同创建者Joel Spolsky所说的“架构宇航员”。
鉴于此，CDA模式最好应用于启动流程时，或变更量相对较小时。不出所料，它在监管更严格的行业中通常更受欢迎。
在线支付提供商PayPal使用集中式设计权威进行治理。在2018年北欧API平台峰会上发言时，当时担任该支付提供商API平台负责人的Jayadeba Jena描述了一个四步流程：
- 定义（API组合对齐）：将包含用例和目标客户的API提案提交给API组合团队。组合团队审查重叠部分，并就API分类法、命名空间和资源名称提供建议。如果批准，则建立一个GitHub代码库来定义API契约，然后可以开始设计阶段。
- 设计（API设计审查）：对于REST API，使用OpenAPI方法，将API契约和示例通过拉取请求提交给中心团队进行审查。一群API设计师会审查规范是否符合设计标准。解决问题和意见，然后，一旦API规范获得批准，它就进入开发阶段。
- 开发（API实现）：实现符合标准的API，例如服务等级协议和日志记录。这是一个迭代过程，会来回提交PR。在这个过程结束时，团队使用工具根据OpenAPI规范自动创建验证测试，来验证实现是否与契约定义匹配。
- 外部化（商家和合作伙伴访问）：提供速率限制、API外观和OAuth范围。创建外部文档。更新SDK。确保API通过集成就绪检查清单。
为了保持一致性，确保遵守公司的安全策略、向后兼容性和生命周期管理。PayPal的CDA维护着一套定义模式、版本控制策略和样式指南的标准。这确保了“客户/合作伙伴获得统一的视图和相同的API体验，”Jena说。
Jena指出，CDA最终成为瓶颈。PayPal的解决方案是培训产品负责人根据组织范围的治理标准来审查其开发团队的工作。中央API设计团队仍然负责制定治理标准，但它不再负责审查每个API。
我们的第二个模式，联邦治理，是一种内部咨询模型。来自集中专家池的个人会加入负责构建API的团队。这些专家可以就关键决策提供建议，也可以被授权代表实施团队做出决策。
如果人员配备适当，联邦治理团队应该有足够的带宽来进行研究，尝试各种方案，并就实践、工具和框架提出有根据的建议。
联邦治理比CDA模式具有三个优势。首先，由于中心团队专家的参与，可以在流程早期做出重要决策。
其次，专家们自己可以获得经验，并将这些经验带回中心团队，确保理解和指导不断改进。第三，那些监督工作的人不太可能成为与现实脱节的“宇航员”，因为他们直接参与了这个过程。
然而，联邦治理是资源密集型的，因为需要大量的专家来确保每个团队都能得到所需的帮助。与咨询公司一样，您必须要么增加员工数量以满足高峰需求，并接受团队成员在空闲时期可能没有太多工作要做，要么您需要准备好裁员以应对工作量下降——或者接受一些瓶颈。
实际上，我还发现，需要付出相当大的努力才能保持专家之间对共享理解的一致性，以避免失去一致性。
汇丰银行从集中式团队转向了联邦治理。“我们已经建立了一个由汇丰银行各部门的‘API 冠军’组成的社区，以了解标准，将其应用于各自的团队，并升级问题或差距，”汇丰银行批发银行首席API架构师John Phenix在其公司博客文章中写道。
然而，汇丰银行也遇到了一些问题。Phenix 写道：“并非所有 API 冠军都拥有同等的经验，因此我们仍然需要一个相当大的中央团队来确保一致性。”该公司的解决方案是提高自动化程度。
他补充道：“自动化测试可以构成DevOps流水线的一部分，确保测试内置于常规的构建、测试和发布周期中。”“这阻止了人们试图操纵治理流程，并确保了更高的API审查覆盖率。”
但Phenix 承认，并非所有检查都能以这种方式自动化：“只需相对较小的投资，就可以在一致性、完整性和可观测性方面获得巨大的收益。”
也许最流行的API治理方法是定向自我治理，这是一种依赖影响而非控制的模式。这种模式最适合DevOps和云原生软件构建方法。因此，它已被Netflix等硅谷公司推广，并被Spotify等欧洲同行效仿。
总体目标是允许高度的自主性，但在这种自主性内，要保持一些护栏——一条“黄金路径”——这使得开发人员更容易做正确的事情。
Wilde告诉我们：“我们越来越多地看到平台的建立以及API治理的融入。”“您可以使用自动化进行CI/CD流水线中的一些设计检查，以使流程尽可能轻量级。”
借鉴“团队拓扑”一书，可以将自我治理与支持团队相结合，这些团队可以帮助处理流对齐团队不擅长的方面，例如API设计。
Wilde 告诉TNS：“你需要提高组织内部发生的事情的有效性和标准化，而不要过于强硬。”“目的是避免团队多次做同样的事情，或者不同的团队选择不同的解决方案。”
这种方法相对于我们已经讨论过的其他两种方法的一个显著优势是执行速度；当团队被赋予对其做出的决策的完全自主权时，他们可以非常快速地行动。它还可以很好地扩展，而无需大量额外招聘。
主要缺点是团队可能会无意中做出不一致的决策，或者为了局部环境而优化决策，从而损害整体利益。“对于内部API，如果它们遵循相同的外观和感觉，这确实有助于提高开发人员的生产力，因为您的开发人员将使用许多不同的API，”Wilde 告诉The New Stack。“这使得制定指南成为一项不错的投资，因为您将在开发人员生产力方面获得回报。”
在英国金融时报任职期间，Sarah Wells担任过许多高级职务，其中包括媒体内容平台的团队负责人，该平台为内部和外部合作伙伴提供对英国金融时报内容的丰富版本的API访问。
从Wells的回忆来看，英国金融时报在自我治理方面的方法似乎相当有机。“我们没有API专家团队，”她告诉The New Stack。“但我们确实有API网关和一些文档标准。”
Wells说：“我们还有一些关于健康检查外观的标准，有了这些，我们发现我们的开发人员更有可能使他们的API看起来像一个通用的API。”“我们讨论了构建API时需要考虑什么，以确保它与所有其他API完全不同；这非常有价值。例如，我们试图确保它可以通过API网关发现，并且我们在命名方式上保持一致。”
正如我们所看到的，即使在同一家公司内，也可以结合不同的方法。并且在不同的地方和不同的时间使用多种方法通常是最佳的。
例如，Netflix以提倡高信任、高自主性的文化而闻名，它使用黄金路径和定向自我治理方法。然而，这家流媒体公司正在更广泛地采用GraphQL的过程中，也使用了集中式治理。 2021年，Netflix的高级软件工程师在InfoQ播客与我交谈时，解释了该公司如何拥有一个模式工作组来监督图的演变。
“这是一个非常依赖人员的过程，”她说。“任何想要成为这个联邦图一部分的团队都需要参与模式工作组。我们有一位数据架构师负责监督这个单一统一图的演变。因此，任何时候有人想要向现有类型添加新的实体或字段，他们都必须来到模式工作组参与讨论。
“我们确保这一切都说得通，而且大家不会随意地向图中添加模式片段。”
最后，无论您选择哪种方法，请记住，治理，就像您的API一样，应该随着时间的推移而发展。持续考虑您的治理模型是否正在做您想做的事情非常重要。