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

Question

基本上，我认为对 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 有一个很好的技术理由这样做。所以请不要以主要基于意见的方式结束这个问题，因为我希望答案不是。

Answer 1

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

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

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

Answer 2

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

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

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

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

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

Answer 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 版本控制就会变得更加可靠