REST API版本控制。每个API都有自己的版本

在URL中指定REST API的版本是很普遍的，特别是在路径的开头，例如：

POST /api/v1/accounts
GET /api/v1/accounts/details

但是，我还没有看到将版本与每个API关联的任何设计。换句话说，我们分别维护每个API的版本。即：

POST /api/accounts/v2
GET /api/accounts/details/v3

使用这种方法，当需要中断更改时，我们可以增加特定API的API版本，而无需增加整个API的版本。

使用此样式而不是通用样式有什么弊端？

— 英·法阿德
source

Answers:

您所谓的单个 REST API可能称为REST API的特定资源集或资源。您也可以将其视为REST API的功能。像任何类型的软件一样，整个程序包都是版本化/更新的，而不是单个功能或资源。

在REST API包的资源是模块化的，因此有可能单独开发和版本化的情况下，您的问题会很有意义。

然后，据我所知，建议的资源定位器命名约定的主要缺点是：

对于API用户，这将导致更加复杂的资源定位器，更难以预测，更难记且更不稳定。
对于模块开发人员而言，现在必须在他们自己的资源定位器中处理此版本控制。
资源定位器的更改变得更加频繁，因为有多个模块正在更新，因此上述缺点是指数式的。

构建API时，您的主要目标之一就是使其易于使用...

您可能会找到一种更好的方法来引入重大更改，甚至用HTTP标头对REST API进行版本控制？

要了解有关HTTP标头方法的更多信息，请参见下面的其他答案：https : //www.troyhunt.com/your-api-versioning-is-wrong-which-is/

— 克莱姆
source

这是一种更好的方法：使用内容协商使用Content-Type和Accept标头对API进行版本控制：

POST /api/accounts
Accept: application/vnd.my-api.account.v1+json

201 Created
Location: /api/accounts/285728
Content-Type: application/vnd.my-api.account.v1+json
{ ... account data here ... }

要获得其他版本，只需在中要求使用其他内容类型Accept。这样，服务器支持的特定版本完全独立于URL结构。只需根据Accept标头选择要响应的版本，同一台服务器就可以支持多个版本。或者，如果您要坚持针对不同版本的不同部署，则可以在服务的不同版本之前放置一个代理，该代理根据Accept标头选择将请求转发给哪个。

这也使您可以在同一端点上支持具有不同语义（不仅是不同版本）的新格式。例如，发布一个帐户列表/api/accounts可能意味着要创建批处理，而您无需为其构建单独的API端点。

— 插口
source

否，接受标头必须是版本信令的最差选择。如果可以，请使用版本标头，如果必须，请使用url路径（即AWS路由）

— Ewan

@Ewan为什么？自定义版本标头意味着不同的版本是相同的资源，而不会通知中间人内容可能不同。缓存代理不会使用您的标头来不向v2请求提供v1缓存的响应。

— 杰克

如果您尚未对API请求使用no-cache，请使用Variant Response标头！内容类型已经具有含义，将其传承给您私人使用只会使消费者的生活变得艰难

— Ewan

@Ewan这就是类型的vnd部分和+语法的用途：表明这是该application/json类型的特定于供应商的子类型。这正是内容类型设计的目的。您的资源有多种格式。您要让客户选择他们想要的格式。此外，没有任何理由API请求不能使用标准的HTTP缓存语义。

— 杰克

如果您修复了myapi v2中的错误，则不会返回新的mime类型。

— 伊万（Ewan）

关键是，如果分别对每个端点进行版本控制，则必须能够分别部署每个端点。

API通常具有一个版本，因为所有端点都在同一代码库中，因此具有共享的依存关系并一起部署。

如果您在进行更改时没有更新版本，因为“哦，我很确定我的更改不会影响到这一点”，那么当您输入错误时就会遇到麻烦。

此外，您将希望同时部署API的v1和v2。通常，这是通过将每个版本部署到单独的服务器并相应地路由流量来完成的。

如果您没有单个API版本，则情况将变得更加复杂。

— 伊万
source