REST API 版本控制。新版本需要包含什么？

Question

假设我有两个端点：example.com/v1/send和example.com/v1/read，现在我需要在/send中进行一些更改，但不能丢失向后兼容性。因此，我正在创建example.com/v2/send，但接下来该怎么办呢？我需要创建一个与/v1相同的example.com/v2/read吗？假设有很多控制器和数百个端点，我会像这样创建一个新版本并更改每个小端点吗？或者我的前端应该使用这样的API？

example.com/v1/send example.com/v2/read

什么是最佳实践？

- ottercoder

---

你提出的方法是足够好的，但要看情况而定。对于更大规模的项目，你可能需要探索API网关和/或服务注册表 - 有些人称它们为“边缘”服务。主要思想是你的“边缘服务”将路由请求到适当的端点，而不会改变客户端。客户端始终会调用example.com/send，但你的边缘服务将根据某些标准将这些请求路由到v1/send或v2/send。你可以使用这个策略来针对特定的客户群体推出变更等。只需在谷歌上搜索此策略，你就会看到很多例子。 - hovanessyan

Answer 1

随着时间的推移，可能会添加新的端点，删除某些端点，模型也可能发生变化等等。这就是版本控制的作用：跟踪变更。

您可能会在一段时间内支持版本1和2，但您很难永远支持两个版本。在某些时候，您可能会放弃版本1，并希望仅完全运行版本2。

因此，请将API的新版本视为可以独立于先前版本使用的API。换句话说，特定客户端应针对API的一个版本而不是多个版本。当然，如果可能的话，最好具备向后兼容性。

---

及时: 不要将版本号加入到URL中，您是否考虑使用媒体类型来处理版本控制？例如，请参考GitHub API。所有请求都由API的默认版本处理，但是目标版本可以在 Accept 头中定义（并且鼓励客户端定义目标版本），使用一种媒体类型：

Accept: application/vnd.github.v3+json

- cassiomolin

---

最好使用媒体类型来处理特定端点的新版本，而不是整个新的URL结构。 - Evert

@Evert 绝对使用媒体类型是处理这个问题的更好方式。 - cassiomolin