使用 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/