API 版本控制【 Eolink 翻译】

版本控制是创建和管理软件产品多个版本的方法。它能帮助用户根据自己的需求来决定使用哪个版本。这种方法同样适用于 API 。

API 的创建基于使用者和开发者共同的需求。它像其他传统的软件产品一样，随着时间的推移而发展，需要不断地迭代更新。

通过下面的例子，我们可以更好地理解什么是 API 版本控制。

假设一个场景，我们希望开发者能够访问客户信息，并且可以通过创建 API 来提供所需的功能。而作为初始版本，我们可以提供只有读取客户信息权限的 API 。然而随着应用程序需求的增加，开发者会增加对客户信息的写入或者访问权限等更深层次的功能进行迭代更新。

作为开发者，需要确定的有：

1、是否需要提供能写入客户信息与更新访问权限的同一 API 的新版本

2、是否需要提供单独的 API 来完成对客户信息的写入和更新访问权限

因为从开发者的角度出发，常规的 API 设计原则是设计出包含附加功能的相同 API 的新版本。由于都需要面对相同的主体——客户信息。因此会有相同 API 的两种版本：

CustomerInfo v 1.0 — 提供对客户信息的只读访问权限功能

CustomerInfo v 2.0 — 提供对客户信息的读、写、更新访问功能

通过 API 的版本控制，CustomerInfo API 的使用者可以根据自己的具体需要来决定使用哪个版本。

当我们想要获得同一个 API 的多个版本时，需要考虑的两个主要因素：

1、指定 API 版本信息的格式是什么

2、使用者可以如何指定所选 API 的版本

因此，在选择指定版本信息的格式时，有以下两种常用的方法：

1、使用发布日期区分——我们可以使用发布日期来标识这个新版本。

示例 — 版本 = ” 2020 年 8 月 8 日 ” | 版本 = “ 2019 年 1 月 1 日 ”

2、使用 major.minor 编号区分——这些编号用于指定同一 API 的不同版本，它可以包含一位、两位甚至三位数字，很多开发者会使用 “ v ” 前缀表示它是一个版本号。

示例 — 版本 = ” 1 “ | 版本 = ” v1 ” | 版本= ” 1.1 ” | 版本 = ” v1.1 ” | 版本 = ” 1.1.1 ” | 版本 = “ v1.1.1 ”

在考虑使用者如何指定版本信息时，同样有三种常用的方法：

1、*使用 HTTP Header * — 将自定义 HTTP 标头用于传递 API 版本信息

示例 — x-customerinfoapi-version:2.1

2、使用 Query Parameter — API 将版本信息作为查询参数传递

示例 — /customerinfo?version=2.1

3、使用 URL — 将 API 版本信息合并到 URL 中

示例 — /v2/customerinfo

我们可以结合上述方法，来获得 API 版本信息。例如，我们能通过使用 URL 的方式来指定 API 的主要版本，使用 HTTP Header的方式来指定 API 的次要版本。

上图演示工具为 Eolink 。

总而言之， API 版本控制是 API 设计与 API 开发中的一个关键。作为开发者，让使用者能够在不同的 API 版本之间进行选择是一个关键的业务差异化因素。

Eolink 作为一款国产构建 API 生态的文档工具，同样提供版本控制的功能，且支持在线使用和私有化部署，感兴趣可以自行试用：www.eolink.com