谷歌有一个 API 问题。正如他们在 2016 年的论文“大规模 API 设计审查”中所述，在过去十年中，生产的 API 数量大幅增长。大量的不一致和可用性问题也是如此。没有一个问题是罪魁祸首。
为了解决这个问题，谷歌建立了一个轻量级、可扩展的分布式设计审查流程。同行评审长期以来一直是健康的现代软件开发实践的主要内容。谷歌在 API 设计方法中的应用最终减少了可用性缺陷，同时比 API 可用性测试更有效。
各种规模的公司，不仅仅是世界上的谷歌，都可以从 API 设计审查过程中受益。但是涉及到什么？
1. 不同的视角加强了 API 设计审查
首先，API 设计审查不是代码审查。相反，设计审查是关于评估服务接口的直观性、完整性和一致性。谈话是关于利用许多人的专业知识和才能。通过这种对话，出现了更强大、更耐用和更一致的设计。
在这次谈话中，API 生产团队应该对问题有最大的了解。这种亲密关系对于确保正确表示各种子系统的操作和运行时期望至关重要。
一些额外的审阅者可能会从新用户的角度来看待 API，提供一组全新的视角，类似于新集成商体验 API 的方式。其他审阅者可能在许多 API 上积累了丰富的经验，提供了与开发团队的深度相匹配的广泛的 API 知识。
2. API 审查从 API 描述开始
在我们分享信息之前，我们必须说同一种语言。通过服务接口传达的业务意图也是如此。在请求和响应 API 中，API 提供的功能可以在写入OpenAPI 规范 (OAS)的描述中捕获。查询 API，如使用 GraphQL 的 API，可以使用 SDL 文档。或者，表达方式可能是 Postman Collection，一种能够捕获端点有效负载和操作信息的开源格式。类似地，更多实时 API 可能会使用AsyncAPI描述来描述它们的接口。
无论选择何种规范，以标准化表示形式捕获 API 的独特操作都可以实现对话。一致的、机器可解析的描述也解锁了自动化工具。利用 linting 之类的自动化进行重要但无差别的语法争论，可以腾出宝贵的时间来讨论更主观的领域，例如 API-product fit。
随着时间的推移，这个 API 定义变成了一个活生生的工件，记录了知识的积累和测试过程中的假设。在设计审查之后，该工件将作为未来客户 API 文档的基础。
3. 预定义的样式指南支持设计审查
一些设计问题可能没有明显的“正确”答案。这种模糊性会导致大型API 生态系统中的不一致和可用性问题。API 风格指南为这些设计问题提供了建议的（有时是必需的）解决方案集合。
几乎所有采用 API 设计审查的公司都会有一套标准，他们将根据这些标准进行审查。这些 API 风格指南应该易于发现、理解和实施。此外，任何风格指南都应该包含一个明确的过程，说明贡献者如何随着时间的推移修改和发展内容。
风格指南内容解决的问题应该与公司寻求在 API 生态系统中推动的结果相关。结果可能包括在以下方面实现更大的一致性：
- 身份验证方法
- URI 和参数命名约定
- 错误处理
- 版本控制
- 有效载荷结构和格式
- 过滤
- 链接和分页
虽然需要这些领域，但 API 设计审查还应不仅评估 API 的形式，还评估其功能。深入了解 API 需要存在的原因以及如何最好地表达其业务价值很难在标准文档中量化。但是，针对这些方面采取额外的努力可能会对最终设计产生相当大的积极影响。
4. API 设计审查的执行情况各不相同
执行设计评审的机制应有所不同，以适应组织内现有的流程和规范。审核可以异步执行，例如在源代码控制、公司 CMS 或共享文档中交换评论。然而，根据我的经验，这些场景在个体贡献者灵活性方面获得了什么，但它们缺乏细微差别和后续参与。很少有人会在他们的日程安排中寻求更多的会议。但是，将必要的利益相关者“现场”聚集在一起可以实现更高程度的交流。这将大大减少所有相关人员的后续澄清和挫败感。
不管审查是如何进行的，一个关键的考虑因素必须是 API 的预期分发范围：
- API 是只有直接开发团队知道的内部组件吗？
- 或者 API 会在业务部门内使用吗？
- API 是否会保留在组织防火墙内，但会成为整个组织使用的关键基础设施？
- 或者我们是否必须扩大潜在用户以包括更大世界的用户，或者因为他们是明确的供应商，或者是没有限制的任何第三方？
您对这些问题的回答可能会显着影响 API 设计审查的性质。您的组织可能会决定，在直接实施团队之外暴露有限的 API（例如微服务）可能根本不需要审查。
5. 反馈应该是双向的
一个健康的设计审查过程并不是单向的信息传播，从审查者流向被审查者。相反，API初稿中的遗漏或疏忽为设计审查人员提供了第一手的、可操作的信息。这种信号应该成为公司的流程、标准和工具的后续修正的基础。
还有其他更正式的方法来评估不断变化的API开发团队的偏好、胃口和成熟度。然而，就额外的时间或精力而言，很少有比在现有的对话中应用同理心倾听更自由的。熟练的评审员会像说话一样倾听，找出哪些方法是有效的，哪些是无效的，以及可能出现的培训需求的模式。