rest - 使用 HATEOAS 对耦合的 RESTful API 进行版本控制

Question

我们有一个 ProductsAPI 来浏览我们网站上可用的产品，这些产品由我们的移动应用程序(Android 和 iOS)使用。以下是基本设计:

URL: /api/products/
Response:
[
    {
        "id" : 123,
        "name" : "abc",
        "detailsUrl" : "/api/products/123"
    },
    {
        "id" : 124,
        "name" : "xyz",
        "detailsUrl" : "/api/products/124"
    }
]

此处，detailsUrl 包含 ProductDetails 页面的 API URL。

现在，我们需要在新版本的应用程序中对 ProductDetails API 的响应进行一些更改，并且需要对其进行版本控制。 URL 将更改为 - /api/v2/products/{id}(我们通过 URL 使用 API 版本控制)。

因为我们不想要以前版本的应用程序中的新响应，我们需要创建一个新版本的 ProductsAPI，它也会发送新的 ProductDetailsAPI url 作为响应。

API 以这种方式耦合。如果我们更改任何子 API 的版本，则父 API 版本也需要更改。处理此问题的推荐方法是什么？我们是否应该改变 API 的版本控制方式(使用 header 或其他方式)？

Answer 1

这是 URL 段中版本控制的结果之一。我建议不要那样做。对于 HATEOAS，超媒体应该只报告相关资源的身份。由客户决定他们想要使用哪个 API 版本。

在大型 API 中，服务具有不一致的版本是很常见的。这会导致在提供的链接中包含 API 版本的任何方法出现许多问题。

1. 广告链接的服务现在要么假设相关资源具有相同的资源版本，要么具有不需要的耦合以生成正确的链接
2. 服务不知道客户端需要或符合的 API 版本。客户可能正在使用 api/orders 1.0 和 api/salespeople 2.0。服务无法知道这一点，这是客户的责任。如果服务在链接中烘焙版本，它可能不是客户想要的，这使得它在 HATEOAS 的上下文中几乎一文不值

在我看来，api/products/123 和 api/v2/products/123 在逻辑上没有区别。归根结底，这两个 URL 都指向标识符为 123 的产品。API 版本表示该产品的不同表示，但不是不同的产品。为此，HATEOAS 实现应以 api/products/123 的形式返回链接，并让客户端使用查询字符串、 header 、媒体类型等按 API 版本决定表示形式。 URL 分段方法是唯一不能以这种方式工作的方法。