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

【问题标题】：Versioning of coupled RESTful APIs with HATEOAS使用 HATEOAS 对耦合的 RESTful API 进行版本控制
【发布时间】：2018-01-02 16:45:15
【问题描述】：

我们有一个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 进行版本控制的方式（使用标头或其他东西）？

【问题讨论】：

标签： rest api restful-architecture hateoas api-versioning

【解决方案1】：

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

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

广告链接的服务现在要么假设相关资源具有相同的资源版本，要么存在不需要的耦合以生成正确的链接
服务不知道客户端想要或与哪个 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 段方法是唯一不能以这种方式工作。

【讨论】：

【解决方案2】：

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

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

【讨论】：

SMH，因此对于更改所有其他服务的任何服务，必须同时更新并神奇地重新部署所有服务，以避免任何版本控制竞争条件。哇。
@PeterRitchie 你这是什么意思？
@Muflix 我的意思是每个服务都有一个共享的依赖关系。如果该共享依赖项发生更改，则每个服务都必须更改。对于任何相互交互的服务，它们都必须为新的依赖项重新构建并同时重新部署，以避免两个或多个服务使用该依赖项的不同版本。
@PeterRitchie 是的，如果客户端/服务想要使用新的 API 版本，您必须重新部署客户端/服务。但以前的版本仍将使用，因此您无需立即或一次性重新部署它们。您更喜欢什么其他解决方案？
@muflix 如果您创建了一个新客户端并且它需要 /v2，那么在部署 /v2 之前它会如何工作？