RESTAPI的语义版本控制？

我已经评估了RESTAPI的许多版本控制模式（头、url等等）。到目前为止，最可靠的方法似乎是url选项：它与代理一起工作，不依赖于模糊的模式，例如

现在，当我环顾四周时，使用基于url的方法的每个人似乎都使用诸如

v1

、

v2

等版本。没有人使用次要版本，甚至没有人使用这样的模式

这引起了一些问题：

• 什么时候增加RESTAPI的版本号（当然，五年更新一次的次数要多于五年更新一次）
• 如果您只是修复了一个bug，那么您可能不会增加版本号，但是如何区分这两个版本呢
• 如果您使用非常精细的方法，那么最终会得到许多需要并行托管的版本。你是怎么处理的

换言之：像GitHub这样的公司，例如，如何使其今天（2015年）只拥有

v3

，而现在他们已经经营了7年了？这是否意味着他们实际上只更改了两次api？我简直不敢相信

---

有什么提示吗？

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

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

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

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

---

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

感谢您的精彩而详细的回答！只剩下一件事：假设这个系统不是在网络上托管的，而是在客户处安装的，我最终会得到很多与给定主要版本略有不同的变体，不是吗？我该怎么处理？换句话说：我不能确定一个客户的

v1

与另一个客户的

v1

是相同的。你能进一步解释一下这种情况吗？您正在开发一个API，该API将在许多客户的服务器上运行，但仅在其本地网络上可用（因此仅在内部使用）？对吗？对。但我们必须支持它。因此，这意味着，客户会打电话投诉RESTAPI存在问题。我们问他们使用哪个版本，他们告诉我们是

v1

。不幸的是，这并没有太大帮助，因为可能有许多

v1

s。当然，我们可以要求特定的服务器版本，但这是一个额外的步骤（我们不确定是否想要它）。这能让问题更清楚吗？是的，我想是的。当然，理想的解决方案是确保所有服务器都是最新版本的软件。但这可能是你无法控制的。那么API中只返回完整版本号的路由呢？然后，您可以将人们（我假设他们大部分是开发人员）引导到该URL（例如

http://12.34.56.789/api/v1/version

）以了解确切的版本。不过，这仍然需要额外的步骤。可能有更好的解决方案，但这是我现在能想到的最好的解决方案；）虽然我从公众的角度完全同意这一点，但我认为在内部（或者如果您向客户提供微服务），对API使用语义版本控制有着显著的优势。如果您的组织有许多相互使用的RESTAPI，那么在它们之间建立API依赖关系是非常有用的。API-A1.0.0一开始就依赖于API-B5.0.0，但是API-A1.1.0的特性开发需要API-B5.1.0的一个新的非破坏性特性。它不一定与软件包版本相同。实际上，这是主要的版本号。我认为资源版本控制更重要，但没有人谈论它。你能进一步解释一下资源版本控制是什么意思吗？Ofc。当资源更改时，它必须更改版本号。通过更新客户机，它必须将本地存储的资源表示的版本号与请求一起发送，这样服务将知道它是否具有资源的新版本。人们称此为etag，但如果您有一个资源或响应包含多个资源，则无法发送多个etag头（afaik），因此您必须在正文中发送版本号。好的，这就清除了它，谢谢：-）