像 Twilio 那样按日期对 REST api 进行版本控制有啥好处？

Posted 2023-03-07

【中文标题】像 Twilio 那样按日期对 REST api 进行版本控制有啥好处？

【英文标题】：What is the benefit of versioning a REST api by date as Twilio does?像 Twilio 那样按日期对 REST api 进行版本控制有什么好处？

【发布时间】：2015-02-19 10:23:10

【问题描述】：

基本上，我认为对 REST api 进行版本控制是个好主意。这是常识。通常你会遇到两种方法来做到这一点：

要么，您的网址中有版本标识符，例如/api/v1/foo/bar， 或者，您使用标题，例如Accept: vnd.myco+v1。

到目前为止，一切都很好。这就是almost all big companies do。这两种方法各有利弊，很多此类内容都在here 进行了讨论。

现在我在 Twilio 看到了一种完全不同的方法，如 here 所述。他们使用日期：

在编译时，开发人员会在编译代码时包含应用程序的时间戳。该时间戳记在所有 HTTP 请求中。

当请求进入 Twilio 时，他们会进行查找。根据时间戳，他们确定创建此代码时有效的 API 并相应地进行路由。

这是一个非常聪明和有趣的方法，虽然我认为它有点复杂。例如，时间戳是编译时间还是 API 发布时的时间戳可能会让人混淆。

虽然我也觉得这很聪明，但我想知道这种方法的真正好处是什么。当然，这意味着您只需要记录 API 的一个版本（当前版本），但另一方面，这使得追踪已更改的内容变得更加困难。

有谁知道这种方法的优点是什么，那么为什么 Twilio 决定这样做？

请注意，我知道这个问题听起来好像答案主要是基于意见的，但我猜 Twilio 有一个很好的技术理由这样做。所以请不要以主要基于意见的方式结束这个问题，因为我希望答案不是。

【参考方案1】：

有趣的问题，+1，但据我所知，他们只有两个版本：2008-08-01 和 2010-04-01。所以从我的角度来看，这只是拼写 v1 和 v2 的另一种方式，所以我认为没有技术原因，只是偏好。

这就是我能找到的关于他们的决定的全部信息：https://news.ycombinator.com/item?id=2857407

编辑：确保您阅读了下面的 cmets，其中 @kelnos 和 @andes 提到了使用这种方法对 API 进行版本控制的优势。

【讨论】：

是的，只有两个版本，但您实际上可以指定任何您想要的日期。假设我今天写了一个应用程序，我不记得当前的版本（日期）编号。所以我只使用今天的日期：2014-12-23。 API 会自动选择不超过我指定日期的最新 API 版本。

@kelnos：这也适用于版本号。例如，您可以拥有/v1/api/ 和/v2/api/，但您也可以公开指向最新版本的/api/，基本上是/v2/api/ 的别名

@Bogdan，通过公开默认/最新版本的 api，正如您在 /api/ 中建议的那样，客户端有接受重大更改的风险，因为最新版本可能是 v2、v3 等。该日期为开发人员提供了一种简单的方法来请求最新的今天，并确保他们免受明天可能引入的重大更改的影响。

@andes：是的。用户 kelnos 也提到了同样的事情，但我不知何故错过了重点。我将更改答案以提示用户也阅读 cmets。

【参考方案2】：

如果您是此类 api 的开发人员，我可以想到的另一件事 使这是一种有趣的方法。

您有 20 种方法，您需要对其中的 1 种方法进行重大更改。

使用 semver（v1、v2、v3 等）您需要一个 v2 api。 你现在所有的 20 个方法都需要响应 v2，但实际上，这些方法根本没有改变，也不是新的。

使用日期，您可以保持未更改的方法不变，并且当请求进来时，它只会选择最好的匹配。

我不知道这是如何实现的，任何有关这方面的信息都会受到欢迎。

【参考方案3】：

我曾经在一家使用日期版本控制的公司工作（因为在每个 api 调用中都有所需的 API 日期参数 ?v=20200630）并且很喜欢它。

它让您没有传统版本控制（v1、v2、v3）那么严格，因为客户端开发人员甚至不需要关心版本号，只需使用当前的构建时间。其他一切都与传统版本控制几乎相同 + 从服务器代码中查看日期检查的小好处 - 您可以轻松查看这个或那个代码路径的历史。

我相信如果我们必须支持多个外部客户端，例如修复 ?v=20200630 中的错误，情况会有所不同 - 没有优雅的方式来指定类似 ?v=20200630.1 的内容。正如您从Twilio's experience 看到的那样，他们只是更改了2010-04-01 的API 版本——因此客户端无法确定它看到的是哪个版本。

所以我的结果是：

当您是典型的初创公司或拥有少量应用程序（例如前端、ios、android）且没有或很少有第三方客户端的小公司时，基于日期的版本似乎更容易、更灵活。基于日期的版本控制使客户端开发人员更容易“只编写代码”，并且由于您控制所有代码，大多数时候您可以通过发布新版本并要求客户端切换到它来修复旧的 API 错误

一旦您开始真正需要维护旧的 API 版本（也就是当您有许多不太可能快速更新的重要客户时），那么 semver 版本控制就会变得更加可靠

【讨论】：

这仍然表明您没有真正支持 REST 的 API，而只是一个 RPC 网关，可能带有外部文档（OpenAPI、Swagger 等）等等。 REST 背后的想法是客户端与服务器分离，并且交换的表示实际上是它们操作的东西。只要双方支持相同的媒体类型，他们就会交换“消息”，因为他们能够处理这些请求。定义可能出现在文档中的各个元素及其语义的媒体类型实际上是重要的部分...

... 而不是端点当前的版本。如果媒体类型缺乏对某些所需功能的支持，例如在某些资源的字段上添加弃用警告，则应定义新的媒体类型以添加​​该功能，或者需要改进当前的媒体类型以支持该选项。这些类似于 html 的定义。尽管它保持向后兼容，但它已经经历了多个“版本”，因此旧版本仍然可以处理。