[ADP-322] 超媒體替代方案

指導原則

• 應(SHOULD)考慮使用 HAL（超文本應用語言）以外的替代方案來構建超媒體回應，因為 HAL 可能不適合所有應用，並且可能會使 JSON 結構變得複雜。
• 應(SHOULD)考慮使用標準的 HTTP 標頭 Link 來替代超媒體中的鏈接(links)。
• 對於嵌入相關資源，考慮直接將相關資源的表示放入主資源對象內(參考ADP-360)，而不是使用 Hypermedia 的 embed。
• 如果你認為超媒體對於你的 API 設計是必要的，應(SHOULD)選擇 HAL 作為實現。

示例

使用 Link 標頭的示例

Link: <http://api.example.com/users/1/friends>; rel="friends"

不使用 HAL 的 JSON 表示示例

{
  "links": {
    "self": "http://api.example.com/users/1",
    "friends": "http://api.example.com/users/1/friends"
  },
  "friends": [
    {
      "id": "2",
      "name": "Jane Doe",
      "age": 28
    }
  ],
  "name": "John Doe",
  "age": 30
}

參考

• Pragmatic-rest-apis-without-hypermedia-and-hateoas
• REST v.s. Hypermedia - hot or not?