使用 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也将发送新的ProductDetailsAPIurl 作为响应。

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

Answer 1

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

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

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

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