什么是 API 版本？

为了扩大用户群并围绕应用程序构建集成生态系统，需要与使用 API 的开发人员之间建立信任。最佳集成依赖于稳定的 API，即很少更改调用方式的 API。

导致 API 不稳定的因素通常是 API 的例行更新。即使是对 API 的一个小改动，也可能破坏客户端应用程序，影响业务，并削弱对服务的信任。

变化虽然不可避免，因此需要进行 API 版本控制。通过明确的 API 版本控制策略，可以在改进 API、吸引新用户的同时，不影响现有用户。

本文将介绍 API 版本控制的概念、重要性以及何时（及何时不）进行版本控制，并回顾标记 API 版本的常用方法。内容以 REST API 为基础，因为它们是基于 Web 的应用程序中最常用的类型。

什么是 API 版本控制？

API 版本控制是管理 API 更改并确保这些更改不会影响老用户调用的策略。一个良好的 API 版本控制策略能够清晰地传达所做的更改，并允许 API 使用者根据自己的节奏决定何时升级到最新版本。

为什么 API 版本控制很重要？

从本质上讲，API 是一种软件，与所有软件一样，API 也需要不断更新升级。然而，与其他常用软件不同的是，即使是微小的 API 更新也可能对下游产生影响，导致用户遇到严重问题。

以应用软件为例，通常会进行更新以修复错误并添加新功能。这些新增功能通常不会干扰普通用户，用户不需要完全适应这些变化。

然而，API 的情况则不同。当第三方应用程序开发人员使用 API 构建集成时，他们期望 API 能够保持稳定。如果在没有考虑客户的情况下更改 API，将迫使他们修改自己的软件，否则应用程序可能会崩溃。

然而，不能指望所有 API 使用者在更新时能够立即适应。他们有其他事务需要处理，将注意力转移到 API 集成上会浪费他们的时间和资源。

因此，API 版本控制不仅仅是更改版本号，还包括尽量避免重大更新，并在这些更新发生时，通过网站、电子邮件和文档等形式清晰地通知客户。同时，版本控制还意味着保留旧版本的 API，以确保客户端集成在无法立即升级到新版本时仍然能够正常运行。这种做法允许在改进 API 的同时，避免破坏现有客户端应用程序，保持用户的使用体验。

什么时候对 API 进行版本控制？

由于 API 版本控制对 API 使用者和开发者而言成本较高，因此最好仅在发生重大更改时才进行版本控制。重大更改是指可能导致客户端应用程序失败的任何变动，通常要求 API 使用者重写其软件以避免问题。

显然，重大变更不会带来良好的用户体验，因为这将迫使用户适应不断变化的技术。他们的产品依赖于 API，而重大更新如果没有得到妥善传达，会破坏这种信任。

因此，尽可能避免进行重大更改和版本控制是明智的。然而，有时这些变更是不可避免的。以下是可能需要进行重大更改的情况：

更改请求或响应数据的格式（例如从 JSON 切换到 XML）。
更改资源的数据类型（例如从字符串变更为整数）。
更改资源名称。
删除一个或多个资源，删除或更改特定资源的属性或方法，或对 API 功能进行任何其他更改。
为客户端 HTTP 请求添加新的必填字段。

如果这些变化不可避免，则需要引入新的 API 版本。

什么时候不需要对 API 进行版本控制？

对于非重大更改，避免进行 API 版本控制是明智的选择。如果有办法在不引入新版本的情况下更新现有 API，并让用户选择是否接受或忽略更新，那么应该尽量采用这种方式。非重大更改可以包含在新版本的 API 中，但它们本身并不足以成为版本控制的理由。

例如，非中断性变更可能包括为资源添加新方法（如 PUT、POST）或添加新资源和端点。在后一种情况下，可以添加资源而不影响现有端点的功能。这确保了现有的集成不会中断，开发者可以选择在需要时采用新端点。

在考虑重大更改时，应首先评估是否有非重大更改的替代方案。这种做法需要更多的思考，而不仅仅是简单地标记新版本号，但其优势在于用户可以继续使用 API 而不受到干扰。

例如，如果打算用另一种资源替换现有资源，可以考虑添加新资源并保留旧资源，然后向用户告知新资源的可用性及其改进之处。

以下代码示例展示了如何在不影响现有集成的情况下添加新资源：

"data": {

   "id": 1,

   "address": "25 First St., Cambridge, MA", // old

   "street-address": "25 First St.", // new

   "city": "Cambridge", // new

    "state": "MA" // new

}

在这个示例中，原始地址被分解为三个新资源：街道地址、城市和州。这样一来，用户可以选择采用新资源，或者继续使用旧的地址资源，确保现有集成的稳定性。

如何进行 API 版本控制？

实际上，API 需要时不时发布新版本，以解决重大错误、安全漏洞或进行性能改进。有时，API 的设计可能从一开始就存在缺陷，需要进行彻底的修正。为了确保这些更新不会中断现有用户的服务，API 版本控制变得至关重要。

在制定版本控制策略时，最重要的一点是确保向后兼容性。通过保持旧版本的 API 处于可用状态并持续支持，使用户可以继续使用旧版本，直到他们准备好升级。这样做实际上是通过分叉旧版本的 API 来创建新版本，同时保持旧版本的功能。

何时停用旧版本的 API 由具体情况决定。例如，分析使用数据可能会发现 v2 和 v3 的用户数量远远高于 v1。如果继续维护 v1 的成本高于潜在的用户流失成本，那么可以考虑弃用 v1。

无论是小更新还是新版本发布，所有变更都应明确告知用户。如果需要停用某个 API 功能或版本，必须提前通知用户并给予他们充分的时间进行调整。需要预料到这种决定可能会导致一些用户不满，甚至流失——但希望不会太多。

关于弃用 API 组件的通知，可能如下所示：

API 版本控制的类型有哪些？

在实际标记新版本时，有几种方法可供选择，其中一些方法可能比其他方法更适合用户群体。以下是将客户端 API 调用路由到不同 API 版本的几种常用方法。

URI 路径

对 API 进行版本控制的最常见方式是在 URI 路径中进行版本标记。这种方法利用 URI 路由将请求定向到特定版本的 API。URI 不仅指定了目标资源，还指明了资源所在的版本。

https://www.example.com/api/v1/resource



or



https://apiv1.example.com/api/resource

版本标识符可以是数字、日期、名称或其他唯一标识符，只要每个版本都是独特的即可。

URI 路径版本控制相对容易理解和实现。然而，如果旧版本的 API 未被保持在可用状态，则用新版本号替换旧 URI 将导致使用旧版本的集成失效，客户端将需要更新他们的软件以继续使用 API。

此外，这种方法不允许仅更新 API 的某一部分。每个端点都必须更新，这样做不仅缺乏灵活性，还更耗费资源，需要为每个版本创建全新的 API。这也违反了 API 设计的一个关键原则：每个资源都应有其唯一的 URI。

Query 参数

在查询参数版本控制方法中，版本号作为查询参数包含在 URI 中，而不是在路径中。

https://www.example.com/api/resource?version=1

这种方法相对容易实现，不需要在更新版本时修改所有 URI。客户端可以通过在其请求中更改查询参数来切换到新版本。如果客户端未在其查询中指定版本号，系统可以默认使用最新版本。

自定义请求标头

您还可以使用请求和响应中的自定义标头设置版本号。这不会改变资源的 URI。

Accept Header

使用 Accept 请求 HTTP 标头进行 API 版本控制时，客户端可以在请求头中指定能够处理的内容类型，从而确定所请求的 API 版本。例如：

Accept: application/vnd.example.v1+json

Accept: application/vnd.example+json;version=1.0

这种方法允许对单个资源进行版本控制，而不必一次性对整个 API 进行版本控制，从而为开发人员提供更细粒度的版本控制。这也意味着，开发人员可以在代码库中节省空间，因为不需要为每个新版本复制整个 API。

然而，这种方法的缺点是实现和测试起来更加复杂。开发人员需要跟踪 API 的哪些部分属于哪个版本，并且要确保每个客户端都能获取到正确的版本。这涉及更复杂的版本管理和交付逻辑，可能增加开发和维护的难度。

通过 API 版本控制保持您的集成完整

通过 API 版本控制保持集成的完整性至关重要。虽然更新 API 是必要的，但也伴随着风险。如果没有适当的版本控制，可能会出现问题，进而导致消费者失去信任，转而寻找更稳定的替代方案。

每次进行更改时，都应尽量减少对客户的影响，这也是正确实施 API 版本控制的核心目标。用户可能不会直接表达感谢，但他们会继续依赖并使用您的服务。