azure api versioning x-ms-version api-version比较

Question

我看到，在Azure中公开的Microsft托管REST API中，有两种方法可以进行版本控制 a）标题中的x-ms-version b）查询字符串中的api-version

我想了解两者之间选择背后的决定是什么。我正在读某个地方，x-ms-versioning是遗留的，前进的方式是查询字符串版本控制模式。这是对的吗？

另外，根据Scot Hanselman's blog，他说查询字符串参数不是他首选的方式，他会选择URL路径段。然后想知道为什么微软采用这个选项？我确实同意每个人都有自己的偏好，但有助于了解从Microsoft选择此选项的原因。

Answer 1

x-ms-version 标头是旧版，仅为了向后兼容而维护。实际上，自2012年引入RFC 6648以来，使用x-前缀的概念已被弃用。

在查询字符串中使用 api-version 是Microsoft REST API Guidelines的§12版本控制中列出的官方约定之一。该指南还允许使用URL段方法，但查询字符串方法是最多产的。

菲尔丁本人对API版本控制有很强烈的意见 - 即不要这样做。实现版本化REST API的唯一普遍接受的方法是使用媒体类型协商。 （例如accept: application/json;v=1.0或accept: application/vnd.acme.v1+json）。 GitHub以这种方式版本化他们的API。

虽然媒体类型协商遵守REST约束并且并非难以实现，但它是最少使用的方法。 为什么可能有很多解释，但实际情况是至少还有其他三种非常常见的方法：查询字符串，URL段或标题。

除了迂腐之外，最常见的形式可能是由于客户可以轻松访问服务。 header方法与使用媒体类型协商没有太大区别。如果要使用标头，那么使用带媒体类型协商的accept和content-type标头是更好的选择。这使我们只使用查询字符串和URL段方法。

虽然URL段方法很常见，但它有一些陷阱，大多数服务作者都不会考虑这些陷阱。它的扩散非常多，“嗯，这就是[在这里插入公司]做到的”。在我看来，URL段方法存在以下问题：

1. 网址不稳定。它们会随着每个新的API版本而发生变化。
2. 作为统一接口的一部分，URL 路径应该用于标识资源。如果您的网址路径为api/v1/products/123和api/v2/products/123，则表示存在两种不同的产品，这是不正确的。 v1与v2网址段意味着不同的表示。在所有API版本中，资源仍然是相同的逻辑产品。
3. 如果您的API支持HATEOAS，那么当您有不一致的资源版本控制时，链接生成就是一个挑战。成熟的服务分类法和REST约束本身旨在帮助发展服务和资源。期望api/orders可以是1.0并且带有api/products/123的引用订单项支持1.0-3.0是完全可行的。如果将版本号烘焙到URL中，那么该服务应生成哪个URL？它可以采用相同的版本，但这可能是错误的。任何其他选项都耦合到相关资源，可能不是客户想要的。服务无法了解客户端理解的不同资源的所有API版本。因此，服务器应仅以vanilla资源标识符的形式生成链接（例如：api/products/123），并让客户端指定要使用的API版本。客户端对链接的任何其他操作都会大大降低支持HATEOAS的价值。当然，如果所有内容都是相同版本或同一资源，则此可能不成问题。
4. 2和3可以通过持久保存资源链接的客户端进一步复杂化。当API版本是日落时，现在资源的任何旧链接都会被破坏，即使资源仍然存在，尽管没有使用预期但过时的表示。

这为查询字符串方法带来了完整的循环。虽然查询字符串确实会因API版本而异，但它不是标识符（例如路径）的一部分。所有版本的客户端的URL路径保持一致。客户端也可以轻松地为他们理解的版本附加查询参数。 API版本通常也是数字，基于日期或两者。有时他们也有一个地位。网址api/products/123?api-version=2018-03-10-beta1可以说比<{1}} 更清晰。

总之，虽然查询字符串方法可能不是版本资源的真正RESTful方法，但它往往会携带更多的预期特征，同时保持易于使用（这不是REST约束）。结合Microsoft REST API Guidelines，这就是ASP.NET API Versioning默认使用开箱即用的查询字符串方法的原因，即使所有这些方法都受支持。

希望这提供了一些有用的见解，因为除了纯粹的偏好之外，不同的样式如何影响您的服务分类。