azure api 版本控制 x-ms-版本 api-版本比较
azure api versioning x-ms-version api-version comparison
我看到在 Azure 中公开的 Microsft 托管 REST API 中，有两种方法可以进行版本控制
a) header 中的 x-ms-version
b) api-查询字符串中的版本
我想了解两者之间的选择背后的决定是什么。我在某个地方读到 x-ms-versioning 是遗留的，前进的方向是查询字符串版本控制模式。这是正确的吗？
另外根据 Scot Hanselman's blog 他说查询字符串参数不是他的首选方式，他会选择 URL 路径段。然后想知道微软为什么采用这个选项？我同意每个人都有自己的偏好，但了解 Microsoft 选择此选项的原因会有所帮助。
x-ms-version header 是遗留的，仅为了向后兼容而保留。事实上，自 2012 年引入 RFC 6648 以来，使用 x- 前缀的概念已被弃用。
在查询字符串中使用 api-version 是 §12 版本控制 中概述的官方约定之一 Microsoft REST API Guidelines。准则还允许使用 URL 分段方法，但查询字符串方法最多产。
Fielding 本人对 API 版本控制有非常强烈的意见 - 即不要这样做。实现版本化 REST API 唯一普遍接受的方法是使用 媒体类型协商 。 （例如 accept: application/json;v=1.0 或 accept: application/vnd.acme.v1+json）。 GitHub 以这种方式版本化他们的 API。
虽然媒体类型协商遵守 REST 约束并且实施起来并不困难，但它是使用最少的方法。 why 可能有很多解释，但事实是至少有 3 种其他非常常用的方法：通过查询字符串，通过 URL 段，或通过 header.
撇开迂腐的想法不谈，最常见的形式可能是由于客户可以轻松访问该服务。 header 方法与使用媒体类型协商没有太大区别。如果要使用 header，那么使用 accept 和 content-type header 进行媒体类型协商是更好的选择。这让我们只剩下查询字符串和 URL 分段方法。
虽然 URL 分段方法很常见，但它有一些大多数服务作者没有考虑到的陷阱。它的扩散非常明显，“好吧，这就是 [insert company here] 的做法”。在我看来，URL 分段方法存在以下问题：
- URL不稳定。随着时间的推移，每个新 API 版本都会发生变化。
- 作为统一接口的一部分，URL路径应该标识一个资源。如果你的 URL 路径是
api/v1/products/123 和 api/v2/products/123，这意味着有两种不同的产品，这是不正确的。 v1 与 v2 URL 段暗示不同的 表示 。在所有 API 版本中，资源仍然是相同的逻辑产品。
- 如果您的 API 支持 HATEOAS，那么当您的资源版本控制不一致时，link 生成是一个挑战。成熟的服务分类法和 REST 约束本身旨在帮助随着时间的推移发展服务和资源。预计
api/orders 可以是 1.0 并且具有 api/products/123 的引用行项目支持 1.0-3.0 是完全可行的。如果版本号被写入 URL，服务应该生成什么 URL？它可以采用相同的版本，但这可能是错误的。任何其他选项都与相关资源耦合，可能不是客户想要的。服务无法知道客户端理解的不同资源的所有 API 版本。因此，服务器应该只生成原始资源标识符形式的 link（例如：api/products/123），并让客户端指定要使用的 API 版本。客户端对 links 的任何其他操作都会大大降低支持 HATEOAS 的价值。当然，如果一切都是相同的版本或相同的资源，这个 可能 是 non-issue.
- 2 和 3 可能会因保留资源 links 的客户端而进一步复杂化。当 API 版本停用时，资源的所有旧 link 现已损坏，即使资源仍然存在，但未使用预期的但已过时的表示形式。
这为查询字符串方法带来了完整的循环。虽然查询字符串确实会因 API 版本而异，但它是一个参数，不是标识符的一部分（例如路径）。 URL 路径对所有版本的客户端保持一致。客户也很容易为他们理解的版本附加查询参数。 API 版本也通常是数字，date-based，或两者兼而有之。有时他们也有地位。 URL api/products/123?api-version=2018-03-10-beta1 可以说 比 api/2018-03-10-beta1/products/123.
更干净
总而言之，虽然查询字符串方法可能不是真正的 RESTful 对资源进行版本控制的方法，但它倾向于携带更多预期特征，同时保持易于使用（这不是 REST约束）。结合 Microsoft REST API Guidelines，这就是为什么 ASP.NET API 版本控制 默认为查询字符串方法 out-of-the-box，即使所有的支持这些方法。
希望这能提供一些有用的见解，说明除了纯粹的偏好之外，不同的风格如何影响您的服务分类。
我看到在 Azure 中公开的 Microsft 托管 REST API 中，有两种方法可以进行版本控制 a) header 中的 x-ms-version b) api-查询字符串中的版本
我想了解两者之间的选择背后的决定是什么。我在某个地方读到 x-ms-versioning 是遗留的，前进的方向是查询字符串版本控制模式。这是正确的吗？
另外根据 Scot Hanselman's blog 他说查询字符串参数不是他的首选方式，他会选择 URL 路径段。然后想知道微软为什么采用这个选项？我同意每个人都有自己的偏好，但了解 Microsoft 选择此选项的原因会有所帮助。
x-ms-version header 是遗留的，仅为了向后兼容而保留。事实上，自 2012 年引入 RFC 6648 以来，使用 x- 前缀的概念已被弃用。
在查询字符串中使用 api-version 是 §12 版本控制 中概述的官方约定之一 Microsoft REST API Guidelines。准则还允许使用 URL 分段方法，但查询字符串方法最多产。
Fielding 本人对 API 版本控制有非常强烈的意见 - 即不要这样做。实现版本化 REST API 唯一普遍接受的方法是使用 媒体类型协商 。 （例如 accept: application/json;v=1.0 或 accept: application/vnd.acme.v1+json）。 GitHub 以这种方式版本化他们的 API。
虽然媒体类型协商遵守 REST 约束并且实施起来并不困难，但它是使用最少的方法。 why 可能有很多解释，但事实是至少有 3 种其他非常常用的方法：通过查询字符串，通过 URL 段，或通过 header.
撇开迂腐的想法不谈，最常见的形式可能是由于客户可以轻松访问该服务。 header 方法与使用媒体类型协商没有太大区别。如果要使用 header，那么使用 accept 和 content-type header 进行媒体类型协商是更好的选择。这让我们只剩下查询字符串和 URL 分段方法。
虽然 URL 分段方法很常见，但它有一些大多数服务作者没有考虑到的陷阱。它的扩散非常明显，“好吧，这就是 [insert company here] 的做法”。在我看来，URL 分段方法存在以下问题：
- URL不稳定。随着时间的推移，每个新 API 版本都会发生变化。
- 作为统一接口的一部分，URL路径应该标识一个资源。如果你的 URL 路径是
api/v1/products/123和api/v2/products/123，这意味着有两种不同的产品，这是不正确的。v1与v2URL 段暗示不同的 表示 。在所有 API 版本中，资源仍然是相同的逻辑产品。 - 如果您的 API 支持 HATEOAS，那么当您的资源版本控制不一致时，link 生成是一个挑战。成熟的服务分类法和 REST 约束本身旨在帮助随着时间的推移发展服务和资源。预计
api/orders可以是 1.0 并且具有api/products/123的引用行项目支持 1.0-3.0 是完全可行的。如果版本号被写入 URL，服务应该生成什么 URL？它可以采用相同的版本，但这可能是错误的。任何其他选项都与相关资源耦合，可能不是客户想要的。服务无法知道客户端理解的不同资源的所有 API 版本。因此，服务器应该只生成原始资源标识符形式的 link（例如：api/products/123），并让客户端指定要使用的 API 版本。客户端对 links 的任何其他操作都会大大降低支持 HATEOAS 的价值。当然，如果一切都是相同的版本或相同的资源，这个 可能 是 non-issue. - 2 和 3 可能会因保留资源 links 的客户端而进一步复杂化。当 API 版本停用时，资源的所有旧 link 现已损坏，即使资源仍然存在，但未使用预期的但已过时的表示形式。
这为查询字符串方法带来了完整的循环。虽然查询字符串确实会因 API 版本而异，但它是一个参数，不是标识符的一部分（例如路径）。 URL 路径对所有版本的客户端保持一致。客户也很容易为他们理解的版本附加查询参数。 API 版本也通常是数字，date-based，或两者兼而有之。有时他们也有地位。 URL api/products/123?api-version=2018-03-10-beta1 可以说 比 api/2018-03-10-beta1/products/123.
总而言之，虽然查询字符串方法可能不是真正的 RESTful 对资源进行版本控制的方法，但它倾向于携带更多预期特征，同时保持易于使用（这不是 REST约束）。结合 Microsoft REST API Guidelines，这就是为什么 ASP.NET API 版本控制 默认为查询字符串方法 out-of-the-box，即使所有的支持这些方法。
希望这能提供一些有用的见解，说明除了纯粹的偏好之外，不同的风格如何影响您的服务分类。