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网址。

现在，我们要求在新版本的应用中对ProductDetails API的响应进行一些更改，并且需要对其进行版本化。该网址将更改为 - /api/v2/products/{id}（我们通过网址使用API版本）。

由于我们不希望在以前版本的应用中使用新的响应，因此我们还需要创建新版本的ProductsAPI，以便在回复时发送新的ProductDetailsAPI网址。

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

Answer 1

我建议使用全新版本，因此父母和子女都会在其网址或媒体类型的使用中添加/v2。媒体类型的概念是客户端发送Content-Type标头以指定应为每个资源返回响应的版本。使用这种方法避免了必须重新版本化整个API，但确实意味着对每个端点进行版本检查。

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

Answer 2

这是在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实现应该以{{1}}的形式返回链接，并让客户端使用查询字符串，标题，媒体类型等来决定API版本的表示.URL段方法是唯一的这种方式无法发挥作用。

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

2 个答案: