API版本控制 - 什么是API版本控制？

由于API是您与API使用者之间的一种形式，它应该是稳定的、一致的、有良好文档支持的，并经过适当的管理。理想情况下，开发者不应该违反这个形式。然而，考虑到有时候他们需要进行破坏性的更改，实际情况往往并非如此。当发生这种情况时，您需要确保已经采取措施，以确保这种更改不会影响您的API使用者。

版本控制是一种实践，通过创建协作的数据共享和编辑控制，确保您的产品在不升级到最新版本的情况下继续为使用者提供更多选择。版本控制是API设计的一个重要部分。它赋予开发者增强其API的能力，而不会在开发新版本时破坏客户端应用程序。版本控制允许客户端继续使用现有的REST API，并在准备好时仅迁移到或更新其应用程序到最新发布的API版本。

何时进行API版本控制

尽管版本控制的时机高度依赖于API使用者的期望，但在进行破坏性更改时，有必要对API进行升级。可能会出现破坏性更改的情况包括：

重命名字段或资源路径。通常在发布API后为了澄清某些内容而进行此操作。
想要更改有效负载结构，包含诸如将整数更改为浮点数之类的内容。
删除API端点的部分，无论是为了修复不良的HTTP动词选择、不一致的设计还是响应代码。

因此，当开发者发布一个API时，他们需要全程管理和监控。如果上述任一项发生，那可能是一个很好的时机对API进行版本控制，以避免破坏现有API使用者的应用程序。

还有一些非破坏性更改，例如添加新的响应参数或新的端点。虽然这些更改不需要更改主版本号，但在进行更改时，必须跟踪API的次要版本。这将有助于支持可能接收到缓存数据版本或面临其他棘手API问题的客户。

API版本控制的类型

面临服务更新的最大挑战是如何处理API合同的更新。当API发生变化时，客户端可能还没有准备好更新他们的应用程序，这就是版本控制策略变得至关重要的地方。不同的公司可以使用不同的方法对其API进行版本控制，但以下是四种常见的API版本控制方式。

1、URI版本控制

这是最自然、也是最常用的方法。它涉及在URL路径中包含版本号。

https://www.example.com/api/1/product s

此策略使用URI路由来确定API的特定版本。由于版本更改了URI，客户端可以缓存资源，这样当有更新时，它将被视为缓存中的新条目。这种方法很简单，但违反了URI应该引用唯一资源的原则。

2、查询参数版本控制

此方法涉及将版本号作为查询参数之一。

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

从实施的角度来看，这种版本控制策略也很简单。如果没有指定查询参数，通过这种方法更容易切换到最新版本。

3、自定义头版本控制

这是一种允许开发者通过包含包含版本号的自定义头来对API进行版本控制的技术。

bashCopy code
curl -H “Accepts-version: V1.” https://www.example.com/api/products

这种方法与查询和URI版本控制不同，因为它不向URI添加填充内容。

4、内容协商版本控制

通过这种方法，开发者可以对单个资源表示进行版本控制，而不是整个API。这提供了更精细的控制，并在代码库中创建了相当大的足迹。

例如：

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

这种方法也不需要实施URI路由规则，这是通过URI路径进行版本控制时引入的。然而，与URI版本化的API相比，这种方法较不易访问。此外，内容协商可能允许您保持干净的URL集，但在某些时候，您将面临为不同版本提供内容的挑战。