REST API的语义化版本控制？

Question

38

我已经评估了许多 REST API 的版本控制模式（header、url等）。到目前为止，最可靠的方法似乎是 url 选项：它可以与代理一起使用，而且不依赖于诸如日期版本之类的模式。

现在，当我四处寻找时，每个使用基于 url 方法的人似乎都使用诸如 v1、v2 等版本。没有人使用次要版本，甚至包括语义化版本控制这样的模式。

这引发了一些问题：

- 在什么情况下会增加 REST API 的版本号（肯定会比五年多更新一次）？ - 如果只有一个错误修复，您可能不会增加版本号，但是如何区分两个版本？ - 如果您使用非常细粒度的方法，您将需要并行托管大量版本。你如何处理？

换句话说，例如 GitHub 这样的公司，如何在已经经营了7年之后仅拥有v3（2015年）？这是否意味着他们只更改了两次API？我几乎无法相信。有什么提示吗？

- Golo Roden

2

实际上，这是主要版本号。我认为资源版本控制更重要，但没有人谈论它。 - inf3rno

你可以进一步解释一下什么是“资源版本控制”吗？ - Golo Roden

1

当资源发生变化时，它必须更改版本号。通过更新客户端，它必须发送本地存储的资源表示的版本号以及请求，因此服务将知道它是否具有资源的新版本。人们称之为ETag，但如果您有多个资源或响应的资源，则无法发送多个ETag标头（据我所知），因此必须在正文中发送版本号。 - inf3rno

好的，明白了，谢谢 :-) - Golo Roden

1个回答

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Nic Wortel · Accepted Answer

对于一个web服务，您只需要主版本号。因为您的使用者只关心不兼容的更改，而且（如果您正确遵循语义版本控制），这些更改只会在发布新的主版本时引入。

所有其他更改（包括新功能、错误修复、补丁等）都应该对您的使用者来说是“安全的”。这些新功能不一定需要被您的使用者使用，而且您可能不希望继续运行包含错误X或Y的未修补版本时间太长。

在您的URL中使用完整的版本号（或您用于API版本控制的任何方法）实际上意味着每次更新/修补API时，您的使用者都必须更新API的URL，并且他们将继续使用未修补版本，直到他们这样做。

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

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