如Twilio所做的那样,按日期对REST API进行版本控制有什么好处？

Question

基本上,我认为对你的REST api进行版本化是一个好主意.这是常识.通常你会遇到两种方法来解决这个问题:

• 要么,你有一个版本标识符在您的网址,比如/api/v1/foo/bar,
• 或者,您使用标题,例如Accept: vnd.myco+v1.

到现在为止还挺好.这是几乎所有的大公司做的.这两种方法各有利弊,这里讨论了很多这方面的内容.

现在,我已经看到了一个完全不同的方法,在Twilio,描述在这里.他们使用日期:

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

当请求进入Twilio时,他们会查看.根据时间戳,他们识别在创建此代码时有效的API并相应地进行路由.

这是一个非常聪明和有趣的方法,虽然我认为它有点复杂.例如,理解时间戳是编译时间还是API发布时的时间戳可能会令人困惑.

虽然我在某种程度上发现这个也很聪明,但我想知道这种方法的真正好处是什么.当然,这意味着您只需要记录一个版本的API(当前版本),但另一方面,它可以使更改的内容更难以跟踪.

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

请注意,我知道这个问题听起来好像答案主要是基于意见的,但我想Twilio有很好的技术理由这样做.因此,请不要将此问题视为主要的基于意见的问题,因为我希望答案不是.

Answer 1

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

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

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

所以我的结果是：

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

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