我有一个面向公众的RESTAPI和SDK，其中管理着多个资源：/api/v1/foo和/api/v1/bar。两者都是当前版本1。

我想对两个端点进行一些破坏性的更改，包括使它们更加一致(头、日期格式等)，但是由于我在一个敏捷环境中工作，我将对一个端点进行更改，释放它，然后稍后更改另一个端点。(假设foo首先得到增强)

我应该如何处理端点的版本控制？版本控制的不同选项的优缺点是什么？除了这些还有其他的选择吗？

选项1：

发布/api/v2/foo并进行新的更改。让/api/v1/foo和/api/v1/bar保持部署状态。想要使用/api/v2/foo的新功能的消费者会将foo的api请求发送到/api/v2/foo，而对bar的请求仍然会发送到/api/v1/bar。有些请求是v1，而另一些请求是v2。

最终，我发布了/api/v2/bar，消费者完全从v1过渡，所以所有请求都是v2。

选项2：

发布/api/v2/foo和新的更改。同时，我还发布了/api/v2/bar，它只是/api/v1/bar的别名。想要新功能的消费者停止拉入v1 sdk并替换它的v2 sdk。所有请求都以v2发送。

最后，当我完成对BAR API的增强时，我遵循上面相同的过程并将所有内容更改为v3。

如果您在api.domain.com或domain.com/api上有一个api，那么用户希望每个资源都具有相同的行为，特别是在处理请求和响应头以及数据格式化时。然后，如果您在api.domain.com/v1上有一个行为，并且要更改它，那么您应该将所有api资源升级到新的行为，并将版本更改为api.domain.com/v2。

即使你是一个敏捷的团队，我认为在版本2中只发布一个API的一个资源，而在版本v1上发布所有其他API的资源，使用不同的格式和请求/响应头，只会在你的API使用者中造成不必要的混淆，也许你应该一直保持这种状态，直到在公开发布之前更新了所有的内容。D如果它不是一个选项，那么释放它就足够了。

如果您认为不可能在同一版本中管理和释放所有资源，则应考虑对资源进行版本控制，而不是将API作为一个整体进行版本控制，例如：

• domain.com/api/v1/someresource将变为domain.com/api/someresource/v1
• domain.com/api/v2/otherresource将变为domain.com/api/otherresource/v2

这种方法并不能解决混乱的问题，因为从长远来看，在同一个API中处理不同的行为可能很复杂，但至少您可以将混乱的预期与API的消费者保持一致。

由于维护不同版本的API也可能会阻碍开发速度，所以我几乎总是倾向于将新资源作为测试版发布，直到可以整体发布新的API版本为止。

我更喜欢选项2。在您对API进行版本控制而不仅仅是某些方法时，从我的角度来看，这种方法似乎更为一致。作为一个开发人员，这是我的观点，我不希望调用同一个API的不同版本。

如果我选择切换到v2，我可以根据发行说明确定foo已经更改，并相应地更新我的应用程序。尽管如此，我仍然可以用它还没有改变的方式调用BAR，而且我不需要考虑我需要调用BAR以及其他所有API v1和FOO via v2的方法。

一旦您发布了v3，您就明确地声明这个新版本已经改变了BAR，我也将处理这些改变。

如果您想到应用程序、桌面应用程序或库，您还可以在发生新的更改时增加整个应用程序的版本号。用户或开发人员也会同时使用应用程序或库版本的一个版本。

因此，我对其余的API没有什么不同，并且允许您的用户一次只能使用一个特定的API版本。