rest - 不同时间发布的多个端点的 API 版本控制

Question

我有一个面向公众的 REST API 和 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。

Answer 1

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

即使您是一个敏捷团队，我认为仅在版本 v2 中发布 API 的一个资源，而在版本 v1 上发布 API 的所有其余资源，具有不同的格式和请求/响应 header 只是在 API 使用者中造成不必要的困惑，也许您应该坚持下去，直到所有内容都在公开发布之前更新为止，如果这不是一个选择，也许将其发布为/beta 就足够了。

如果您认为不可能在同一版本中管理和释放所有资源，您应该考虑对资源进行版本控制，而不是对整个 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 版本为止。