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

Question

我们有一个ProductsAPI来浏览我们网站上可用的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 版本控制方式（使用标头或其他东西）？

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的形式返回链接，并让客户端使用查询字符串、标头、媒体类型等来决定 API 版本的表示形式。 URL 段方法是唯一的方法不能这样工作。

Answer 2

我会推荐一个全新的版本，这样父母和孩子都会在他们的 URL 中添加一个/v2 ，或者使用媒体类型。 媒体类型的想法是客户端发送 Content-Type 标头来指定应该为每个资源返回哪个版本的响应。 使用这种方法避免了重新版本整个 API，但确实意味着对每个端点进行版本检查。

正在使用的媒体类型的一个很好的例子是 GitHub API，您可能会发现阅读此处的文档很有用： https : //developer.github.com/v3/media/