REST API 的语义版本控制？答案

【问题标题】：Semantic versioning of REST apis?REST API 的语义版本控制？
【发布时间】：2015-03-10 04:38:28
【问题描述】：

我已经评估了许多 REST API 的版本控制架构（标头、网址……）。到目前为止，最可靠的方法似乎是 url 选项：它适用于代理，并且不依赖于诸如 dates for versioning 之类的模糊模式。

现在，当我环顾四周时，每个使用基于 url 的方法的人似乎都使用v1、v2 等版本。没有人使用次要版本，甚至没有人使用像 semantic versioning 这样的架构。

这引发了一些问题：

什么时候增加 REST api 的版本号（当然，您对它的更新比五年一次的要多）？
如果您只是修复错误，您可能不会增加版本号，但是您如何区分两个版本？
如果您使用非常细粒度的方法，您最终会得到很多个需要并行托管的版本。你是怎么处理的？

换句话说：像 GitHub 这样的公司如何做到今天（2015 年）只有v3，而他们已经经营了 7 年？这是否意味着他们实际上只更改了两次 API？我简直不敢相信。

有什么提示吗？

【问题讨论】：

其实就是主版本号。我认为资源版本控制更为重要，但没有人谈论它。
您能否进一步解释一下您所说的资源版本控制是什么意思？
Ofc。当资源更改时，它必须更改版本号。通过更新客户端，它必须将本地存储的资源表示的版本号与请求一起发送，因此服务将知道它是否具有资源的新版本。人们称之为 etag，但如果你有一个资源或具有多个资源的响应，则不能发送多个 etag 标头（afaik），因此您必须在正文中发送版本号。
好的，已经清除了，谢谢:-)

标签： api rest versioning semantic-versioning

【解决方案1】：

主要版本号是 Web 服务所需的全部内容。因为您的消费者只关心向后不兼容的更改，并且（如果您正确地遵循语义版本控制）这些只会在新的主要版本发布时引入。

所有其他更改（包括新功能、错误修复、补丁等）对您的消费者来说应该是“安全的”。这些新功能必须供您的消费者使用，并且您可能不想继续运行包含错误 X 或 Y 的未修补版本超过必要的时间。

在您的 URL 中使用完整的版本号（或您用于 API 版本控制的任何方法）实际上意味着您的消费者必须在您每次对 API 进行更新/错误修复时更新您的 API 的 URL，并且他们会保留在他们这样做之前使用未打补丁的版本。

当然，这并不意味着您不能在内部使用语义版本控制！只需使用第一部分（主要版本）作为 API 的版本号。在您的 URL/标头/其他版本控制系统中包含完整的版本号是没有意义的。

所以回答你的问题：每次发布新版本时都会更新 API，但只有在有新的主要版本时才会发布新的 API 版本。这样，您只需托管几个不同的版本（当然，随着时间的推移，您可以弃用旧版本）。

【讨论】：

感谢您非常详细的回答！只剩下一件事：假设系统不是托管在网络上，而是安装在客户那里，我最终会得到给定主要版本的许多稍微不同的变体，不是吗？我该如何处理？换句话说：我不能确定一个客户的v1 与另一个客户的v1 的含义相同。
你能再解释一下那个场景吗？您正在开发一个 API，它将在许多客户的服务器上运行，但只能在他们的本地网络上使用（因此只能在内部使用）？对吗？
正确。但我们将不得不支持它。因此，这意味着客户致电并抱怨 REST api 存在问题。我们询问他们使用哪个版本，他们告诉我们是v1。不幸的是，这并没有太大帮助，因为那里可能有很多v1s。当然，我们可以要求特定的服务器版本，但这是一个额外的步骤（我们不确定是否要拥有它）。这会让问题更清楚吗？
是的，我想是的。当然，理想的解决方案是确保所有服务器始终与最新版本的软件保持同步。但这可能超出了您的控制范围。 API 中只返回完整版本号的路由呢？然后您可以将人们（我假设他们主要是开发人员）引导到该 URL（例如http://12.34.56.789/api/v1/version）以找出确切的版本。不过，这仍然需要额外的步骤。可能有更好的解决方案，但这是我现在能想到的最好的解决方案；）
虽然从公众的角度来看我完全同意这一点，但我认为在内部（或者如果您向客户提供微服务）对 API 使用语义版本控制具有显着优势。如果您的组织有许多相互使用的 REST API，那么在它们之间建立 API 依赖关系会非常有用。 API-A 1.0.0 依赖于 API-B 5.0.0 开始，但是您的 API-A 1.1.0 的功能开发需要 API-B 5.1.0 的新的非破坏性功能。它不一定与软件包版本相同。