时间戳

首页 > 解决方案 > REST API 的版本控制格式

c# - REST API 的版本控制格式

问题描述

我尝试按照Microsoft REST API 指南了解 REST API 的版本控制策略，并尝试将其用于我的 ASP.NET Core 解决方案。

从指南：

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

  • 嵌入在请求 URL 的路径中，在服务根的末尾：https://api.contoso.com/v1.0/products/users

  • 作为 URL 的查询字符串参数： https://api.contoso.com/products/users?api-version=1.0

在这两个选项之间进行选择的指导如下：

...

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

我想我不太明白“不能进化”是什么意思——

这意味着 API 中描述的关系的命名和结构在 API 发布后无法演变，即使跨版本发生重大更改也是如此。

您能否给出一个扩展的定义？

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

谢谢 ： ）

标签： c#asp.net-coreversioning

解决方案

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

使用路径参数版本控制，您可以：

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

如果使用查询参数，他们建议更改资源名称，其中某些资源仅支持某些版本参数。

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

推荐阅读