REST版本控制格式

Question

我尝试为REST的后续Microsoft指南引入版本控制策略，并尝试将其用于我的ASP.NET核心解决方案。

从指南中：

支持用于指定REST请求版本的两个选项：

• 嵌入到请求URL的路径中，在服务根目录的末尾：https://api.contoso.com/v1.0/products/users
• 作为URL：https://api.contoso.com/products/users?api-version=1.0的查询字符串参数

在这两种备选方案之间作出选择的指南如下：

..。

1. 即使通过API的未来版本，保证REST路径稳定性的服务也可以采用查询字符串参数机制。这意味着API中描述的关系的命名和结构不能在API发布之后发展，即使是跨版本的更改也是如此。
2. 无法确保未来版本的URL路径稳定性的服务必须将版本嵌入到URL路径中。

我想我不太明白‘不能进化’在-

这意味着API中描述的关系的命名和结构不能在API发布之后发展，即使是跨版本的更改也是如此。

你能给出一个扩展的定义吗？

您是否有任何服务示例无法确保未来版本的URL路径稳定性？

(谢谢：)

Answer 1

如果您预期URL本身中的资源名称会发生更改，Microsoft指南建议不要使用查询参数来控制主要版本。

对于path参数版本控制，您可以拥有：

https://api.contoso.com/v1.0/products/users https://api.contoso.com/v2.0/items/customers

对于查询参数，他们建议更改资源名，其中一些资源只支持某些版本参数。

正如@Archer说的那样，最常见的做法似乎是使用一个没有点或subversion的主要版本，并且查询参数版本很少，只有像FourSquare (https://developer.foursquare.com/docs/api/configuration/versioning)这样的版本日期参数(除了主要的路径版本之外通常使用它)，并且通常控制比资源名称更改更小的API更改。