API first

发表于 更新于 阅读次数：

本文是 Understanding the API-First Approach to Building Products
的翻译，进供学习交流。如有翻译不当，请斧正。所有权归原作者。侵删。

swagger smartbear

———— 珍妮特·瓦格纳（Janet Wagner）

Web API已经存在将近20年了，但是直到最近几年，“API优先” 的概念才在软件团队中引起关注。采用API优先方法构建产品的开发人员数量正在增加。
因此，今天我们将首先向您介绍API的概念，以及为什么这种方法越来越重要。

API优先方法意味着什么？

以API优先意味着对于任何给定的开发项目，您的API都被视为“一等公民”。关于项目的一切都围绕着这样的想法：最终产品将由移动设备使用，
而API将由客户端应用程序使用。API优先方法涉及开发一致且可重用的API，这可以通过使用
API描述语言
来约束API的编写。这些约束可能会让API设计花费更多的时间。它还经常涉及额外的计划和利益相关者在编码前就设计提供的反馈。

API越来越流行

现在，人们通过手机、笔记本、平板和台式机等不同设备中的应用程序使用数据。考虑到不同设备的屏幕尺寸，就需要构建能在所有设备上显示正常且良好运行的程序。
API使公司可以将功能分解为单独的自治服务（也称为微服务）。基于微服务的程序可以在所有设备上都具有良好的用户体验(UX) 。API有限策略可以组织构建应用于
所有程序的API，而且可以对所设备、平台、操作系统有效地开发和维护。

API优先方法的好处

以API优先的产品构建方法可带来诸多好处，包括但不限于：

开发团队可以并行工作

API 首先建立约定[^1]。在 API 约定[^1]之下，团队可以同时使用多个 API 。开发人员不必发布 API 更新就可以继续使用下一个 API ，团队根据 API 约定 mock API
测试 API 的依赖性。

减少开发成本

API 和代码可以在许多不同项目上重用。当开发团队需要构建新的应用时，不必重头开始，这既费时又费钱。API 优先设计还允许在编写任何代码之前就解决大多数问题，
避免在 API 于应用集成时出现问题。

加快上市速度

使用允许导入 API 定义文件的工具，可以自动构建 API 的大部分过程。像 SwaggerHub 允许导入 API
定义文件，像 API 文档、SDK、和 mock API 都可以自动生成。自动化极大地加快了API和应用程序的开发。

API首先还可以为应用程序添加新的服务和技术，而不必重新架构整个系统。在开发应用程序方面，竞争非常激烈，因此必须快速开发应用程序。
如今，应用程序不仅必须经过精心设计，而且必须在六个月内推向市场。

确保良好的开发人员体验

API的使用者通常是开发人员，开发人员的经验（DX）可以决定API的成败。 API 优先，可以保证开发人员在使用您的 API 时有良好的体验。。设计良好、文档良好、
一致性 API 可以为开发人员提供了积极的体验，因为它更容易重用代码，更容易让开发人员参与其中，并且减少了学习曲线。

降低故障风险

对于大多数的公司而言，API几乎用于每个业务流程-从营销和销售到通讯和面向消费者的应用程序，这意味着API可以对您的业务的各个方面产生正面或负面的影响。
API首先通过确保API可靠，一致且易于开发人员使用来降低失败的风险。

计划您的API优先程序

既然您已经知道API优先方法在产品开发中的一些好处，那么您应该如何计划和实施API优先方法呢？

以下几点是你在计划 API 优先的时候要注意的：

  1. 集思广益：首先，有必要确定您的业务提供的关键服务和业务能力。弄清楚应该构建的API的种类以及应该通过API提供的服务。
    另外，找出并写下每个API的用例。根据这些用例写下潜在的端点。
  2. 建立 API 受众: 谁是您组织中的利益相关者？您的API计划应包含尽可能多的人-您需要公司范围内的支持，并需要组织内团队共享的愿景。然后，
    利益相关者可以就整个组织之间的交互达成一致，以使API保持一致。
  3. 设计 API 约定[^1]: 约定[^1]为设计 API 建立了一套标准和最佳实践。确保描述和记录所有API。从端点名称和URL到错误代码和版本控制，
    确保所有API的工作方式相同。一致性是关键。
  4. 定义风格指南: 全面，具有凝聚力的风格指南可确保组织服务的团队之间的一致性。API状态代码，版本控制，错误处理等将被标准化，
    以确保以相同的方式设计API。使用SwaggerHub之类的工具为组织中的所有API创建样式指南。
  5. 实施API治理: API治理流程可以帮助强制执行既定标准并增强预期结果。我们将在即将发表的博客文章中讨论API治理。
    进行对等代码审查还可以帮助确保遵循API设计标准，并确保开发人员在生产高质量的代码。
  6. 自动化流程: 使用SwaggerHub之类的工具来自动化流程，例如生成API文档，样式验证，API模拟和版本控制。另外，使API成为自助服务，
    以便开发人员可以立即开始使用您的API构建应用。提供交互式文档或沙箱，以便开发人员可以试用API端点。
  7. 跟踪和管理您的API产品组合: 通过跟踪和管理您的API产品组合，避免重复代码和构建冗余API。实施有助于您跟踪和管理API的系统。
    您的组织和平台越大，跟踪API及其依赖性的难度就越大。
  8. 为内部开发人员创建网站: 为内部开发人员创建一个中心位置，一个存储所有API的内容的地方-API规范，文档，合同等。例如，据InfoQ的一篇文章，
    贝宝（PayPal）为开发人员建立了门户，它是“贝宝（PayPal）中访问量最大的内部应用程序之一”。贝宝的门户网站包含所有API，文档，仪表板等的清单。

API作为一等公民

API优先的产品构建方法可以使您的组织从许多方面受益。API优先方法要求团队计划，组织和共享其API程序的愿景。它还需要采用支持API优先方法的工具。

[^1]: 这里的约定其实就是 API 设计规范。