Rest API Hateoas：API 響應應該將標識符作為硬編碼還是作為占位符？

Question

Link to the HATEOAS This is the link to the Hateoas article (snapshot below) where the identifiers of the resource is part of the URL ie 12345. Here the API response has the final API relative URL ie /accounts/12345/deposit and the client只需要擊中它。

Link to the Github Users API This is the link to the Github API (snapshot below) where there are lots of placeholders for identifiers. 客戶端將如何修改這些 URL 並在這些占位符中添加值？ 例如，{/gist_id}、{/other_user}。

傳遞帶有 id 值而不是占位符的 URL 不是更好嗎？ 為什么以及何時依賴不同的客戶端在這些占位符中添加值？

Answer 1

超文本作為應用程序 state (HATEOAS) 的引擎不僅僅是使用鏈接。 從本質上講，它非常成功地執行了在 Web 上使用了二十年的交互 model。 在 web 上，服務器通常“教”客戶端（瀏覽器）通過鏈接關系實現某些目標，可用於自動下載相關資源或提示參考資源，以及Web ZAC68B6236C和 8A9FECZE8ACCE 定義語法每個支持的（輸入）元素的語義，即文本字段，select 一個或多個選擇的選項元素，下拉菜單甚至 slider 小部件。 基於每個元素的可供性，客戶端知道，即按鈕想要被點擊或按下，而文本字段想要一些用戶輸入和東西或帶有prefetch鏈接關系名稱注釋的鏈接可以在當前頁面自動下載完成加載，因為客戶端可能會在接下來調用它，或者preload鏈接關系可能會指示用戶代理在當前頁面加載過程的早期加載引用的資源。

該表單不僅向客戶端介紹了資源具有的支持字段，還向客戶端介紹了將請求發送到的目標 URI、HTTP 方法在發送請求時使用的方法以及媒體類型，在 Web ZAC68B62ABFDC68ACCE0C26 的情況下通常隱式設置為application/x-www-form-urlencoded 。

在理想世界中，客戶端只使用服務器提供的信息。 不幸的是，世界並不完美，隨着時間的推移，人們提出了許多其他解決方案。 其中之一是URI 模板，它基本上允許客戶端使用基本 URI 並用具體值填寫某些占位符。 由於使用模板需要了解 URI 意圖或您需要傳遞的參數，因此此類功能僅作為媒體類型支持的一部分才有意義。

普通 JSON ( application/json ) 默認情況下不支持任何 URI，因此接收普通 JSON 有效負載的用戶代理可能無法自動用開箱即用的具體 URI 替換模板 URI。 JSON Hyper-Schema ( application/schema+json ) 嘗試將鏈接和 URI 模板支持添加到普通的 JSON 有效負載中。 但是，用戶客戶端需要使用適當的媒體類型來提示，以便自動解析完整的 URI。 因此，用戶代理還必須支持相應的媒體類型，否則它將無法成功處理文檔（將模板 URI 解析為真實 URI）。

JSON 超文本應用語言又名HAL JSON也支持鏈接的 URI 模板。 application/collection+json確實支持兩種模板—— 查詢模板和對象模板。 引物類似於 URI 模板，允許 append 在發送請求時向目標 URI 提供某些查詢參數，而后者允許定義整個 object，其中包含用於在集合中添加或編輯項目的所有輸入元素. JSON-LD並不真正支持 URI 模板 AFAIK，盡管它使用所謂的上下文的概念，其中某些術語可用於縮寫 URI。 因此，可以在諸如http://schema.org/name之類的 URI 的上下文中使用諸如name之類的東西。

如您所見，對 URI 模板的支持取決於用於交換數據的媒體類型。 In the case of the outlined github example GET /users/:username this more or less resembles a typical Web API documentation, similar as it is done in a Swagger API documentation , that unfortunately has hardly anything to do with HATEOAS .

Answer 2

對於您的頂級示例（銀行），您絕對應該包含完整的 URL 和帳號（ID），以便客戶不需要翻譯/替換任何內容。 這是 HATEOAS 最常見的情況。 但是，GitHub 確實為可能包含多個值的端點提供了那些“占位符”。 您不能在響應中包含每個用戶的“following_url”，這是不切實際的。 因此，您必須以另一種方式確定“other_user”值並進行替換。 就個人而言，我的任何應用程序都沒有這個用例，而且我所有的 HATEOAS URL 都類似於您的第一個示例（盡管我更喜歡完整的 URL，而不是相對的）。 除非你有像 GitHub 這樣的特殊情況，否則沒有必要使用這些占位符。 即使是 GitHub 也只使用它們可能是多個值的地方。 對於固定值 URL，它們在 URL（“octocat”）中具有用戶名（如您的帳號）。

Answer 3

根據我的說法，我們不應該在正文中直接給出 url 我們應該始終參數化 api 並在那里獲取詳細信息。 在簡單的情況下，如果數據 ID 發生變化，則每次數據都需要更新詳細信息 url。 否則，如果它是動態的，您將永遠不會遇到這個問題。 這也屬於最佳實踐。