如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

编辑：请务必阅读下面的评论，其中@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 中看到的那样，他们只是更改了 API 版本 2010-04-01 - 因此客户端无法确定它看到的是哪个版本。

所以我的结果是：

• 当您是典型的初创公司或拥有少量应用程序（例如前端、iOS、Android）且没有或只有很少 3rd 方客户端的小公司时，基于日期的版本似乎更容易、更灵活。基于日期的版本控制使客户端开发人员“只编写代码”更容易一些，并且由于您控制所有代码，因此大多数情况下，您只需发布新版本并要求客户切换到它即可修复旧的 API 错误< /p>

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