API 管理

「API」是什么

在谈 API 的管理之前，我们首先要弄清楚我们要管理的到底是什么东西，「API」这个术语本身具有二义性，当我们在不同的上下文谈论它的时候，其实是在说不同的东西或者说「API」扮演的不同角色：

• 它可以被当作「应用接口」，比如：「调用支付服务的支付 API」
• 它也可以指将代码部署到线上环境后得到的「可访问数据服务」，比如：「发布 xx API」
• 而我们有时也会称那些代码与部署元素本身为「API」，比如：「Market API 的 Pipeline 挂掉了」，「获取所有用户 API 的测试红了」

上面的说法都没有问题，而且都在 API 管理的范畴之内，实际上这三种场景指出了 API 的三个要素：

• Interface——接口
• Implementation——实现
• Instance——实例

什么是 API 管理

1. API 产品管理：谈到 API 的管理，我们的第一反应通常是「设计——构建——发布」这三个显而易见的环节，而实际上我们还需要考虑以下内容，我们可以称之为 API 的几大支柱：

   • 对其进行测试
   • 记录文档并发布文档到门户网站以供合作者学习使用
   • 保护 API 的安全，监控其状态
   • 在生命周期内对其进行维护（处理更改）——「空中加油机」
   • ……

2. API 团队管理：在企业级的 API 管理场景中，我们通常需要管理多个功能团队所维护的不同知识领域的 API 资源，好在对于单一产品的管理经验是可复制可传播的，因此管理 API 团队其实是在考虑如何做好跨团队知识沉淀与能力培养。

3. API 成熟度：在 API 整个生命周期的不同阶段，对于 API 不同支柱的关注度应该是不一样的，了解并清楚地定义 API 的成熟度能够使我们将有限的资源与精力投资在当前阶段更有价值的事情上。比如：对于早期的 API 而言，我们主要专注于设计与构建方面，而减少对于文档的工作；而在 API 上线之后的阶段，我们则应该花费更多的时间来监控 API 并保护它免遭滥用。

4. API 标准化管理：集中管理大量的 API 与管理与维护单一的 API 是两个完全不同的概念。这里所面临的最大的挑战是在对 API 进行中心化的管理、保证一定程度的一致性的同时，不降低 API 的性能瓶颈与稳定性。

5. API 的业务管理：除了单一 API 的生命周期管理以及企业范围内的 API 标准化管理的技术细节，还必须牢记所有这些工作都是为了支持业务目标。API 不仅仅是 JSON 或者 XML，它们也是将企业各个业务单元链接在一起并产生业务价值的一种方式。 当 API 没有真正创造价值的时候，它们只能被称为「在制品」，积极发现已有的 API 能够为企业带来什么样的业务价值并驱动其落地为「已完成工作」同样是 API 管理的一项要务。

API 平台化管理难在哪里

难点 1: Scope——范围

长期管理 API 时，中央软件体系结构团队应该重点关注什么？ API 管理平台最大的挑战之一是实现「适当级别」的中心化控制，更加困难的点在于随着管理平台的成熟，「适当级别」本身也在发生变化。随着构建与使用 API 团队数量的增加，各种各样的知识、观点、经验也在不断增加。想要在所有的团队中保持一致是不现实的，有时候并不是他们不想遵守已经发布的准则，而是有自己的不得已之处，比如：他们依赖另一套第三方产品……作为 API 管理平台，必须兼顾诸如此类的复杂场景，在我们给出的准则中尽可能覆盖所有团队的问题领域，要避免消除合理的多样性，比如：

• 从「所有 API 必须使用以下 URL 模式...」， 转变到「通过 HTTP 运行的 API 应该使用以下 URL 之一」；
• 从「所有的 Web Restful API 服务应该采用 Python Flask 构建」， 转变到「Web Restful API 服务应该采用以下技术栈之一……」；

难点 2: Scale——规模

随着 API 管理规模的增大，最初运行良好的管理策略难以跟上节奏。API 平台化管理相比较于维护单一的 API 产品需要考虑的问题域是完全不同的，平台中的 API 数量越多，调用量越大，他们之间进行交互的可能性就越大，其中某些交互会因为 API 的变更产生意外的结果（错误），并且这些错误很可能难以追溯并修复。这就为 API 平台管理带来了另一项挑战：如何对运行中的 API 制定并应用合适的标准来减少意外的变更。

难点 3: Standards——标准

随着 API 管理的规模化，管理和治理工作通常需要从有关 API 设计和实施的详细建议转变为 API 生态系统更通用的标准化，使团队能够自由地进行细节上的决策。

API 平台化管理应该管什么

技术

俗话说「万事开头难」，在任何软件项目的初期，我们都需要面临一个非常复杂的问题：选择技术栈。因为决策需要考虑的不确定因素实在太多了，比如：技术栈的更迭、项目组成员的技术背景、项目组成员的意愿等。而对这个处于项目早期的过程我们又不应该冒太多的资本风险来进行大量的讨论与研究。

那么工程领域应对此类问题最常用的方法就是「约束」，组织内部通常会选择和支持一部分工具，并为其提供清晰、详细的技术指南。限制选择可以使得团队做事更快，并降低 API 变更的速度。

但作为 API 管理「平台」，一个很重要的任务就是明确地感知平台规模的变化，随着新的业务单元与跨时区团队的集成，「多样性」就成为了生态系统中的一大动脉，「平台方」需要根据规模的变化在合适的时间点增加「技术指南」的多样性而非一味的限制。

团队

技术并非 API 管理的唯一影响因素，在没有平台化之前，每个 API 的整个生命周期由一个全功能团队进行管理，但随着 API 程序的规模和范围的增加，构建和维护 API 所需要的技术数量会显著上升，不可能每个 API 开发团队都为自己的 API 单独部署一套监控、报警、流量限制、门户网站、文档网站等「基建类」服务。

这时可能需要成立一个专门的团队来负责设计和构建供其他团队使用的数据中心监控接口，他们会使用特定的工具集来做特定的事情，比如：使用 prometheus 或者 sumologic 来做请求、日志等数据的收集。 同时，可能还会有另一个团队专门整合生态系统中的数据资源来满足特定场景的业务，他们也许会采用类似 GraphQL 的查询工具来专门为手机应用构建数据接口。

除了成立专门的「基建」团队来做特定的「基建」工作之外，转变组织的决策方式也可以是团队管理的另一个突破点。在企业数字化的初期，团队小且经验不太充足，将技术决策集中到一个单独的指导组能够起到立竿见影的效果，他们通常被冠以「架构组」或者「HOT Office」诸如此类的名字。但是随着数字生态系统的扩张且技术面越来越不均匀，技术决策工作集中在较小的范围是有问题的，单独的技术领导团队不可能保持跟进每一个工具、框架与日常工作的细节，更何况对全球化的团队来说还有时区的限制。因此，可以考虑的解决方案是将决策的过程分解为相互独立的「决策元素」：初始化决策——选项清单——作出选择——授权——执行决策——挑战决策，并将这些「决策元素」的决策权分配到组织中的不同层级。

治理

正如领导领域，在 API 的治理中，如果有明确的范围与规模限制，提供详细的操作指导和过程文档绝对是最有效的，比如：如何设计 URL、URL 的命名规范、HTTP 头中的版本号应该用什么字段等等。

但随着 API 生态系统的扩张，维护应用于所有团队的单一指导文档是极其困难的，技术的多样性在企业的生态系统中是一种积极的力量，我们应该尝试驾驭它而非回避，这也是为什么治理文档需要从「直接过程指令」转变为通用原则，这种治理文档的演进模式同样适用于 UI/UX 的通用指南，比如：尼尔森诺曼集团的「十大交互设计原则」。

同时，对于跨国或者大型组织，治理需要从「发布原则」转换到「收集建议」，分布式的组织结构决定了中心化的治理模型并不适用，这一点是符合「康威定律」的。所以总的来说，随着规模的增长，API 的治理模型需要从直接建议转为提出通用原则，再到收集和分享公司团队的实践经验。