ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

[ADP-145] Link ​

reviewing phase 1

添加 OpenAPI 範例以及關聯 ADPs

指導方針 ​

  • 應該(SHOULD)在回應中包含 Link 標頭，以提供客戶端有關相關資源的信息。
  • 必須(MUST)優先考慮現有的自定義連結關係類型。
  • 必須(MUST)優先考慮 IANA 註冊的連結關係類型。
  • 必須(MUST)對自定義連結關係類型使用絕對 URI。
  • 必須(MUST)使用 CURIE 連結關係類型。

IANA 連結關係註冊表 ​

互聯網分配號碼管理局（IANA）維護一個連結關係的註冊表，定義了可以在 Link 標頭中使用的常見 rel 值。一些與 API 設計相關的常用 rel 值包括：

  • self: 指當前資源。
  • next: 指序列中的下一個資源。
  • prev: 指序列中的上一個資源。
  • first: 指集合中的第一個資源。
  • last: 指集合中的最後一個資源。
  • collection: 指一組資源。
  • item: 指集合中的單個項目。
  • profile: 指描述當前資源的資源。
  • external: 指與當前資源相關的外部資源。
  • curies: 指定義一組 CURIE（緊湊 URI）以供文件使用的資源。
  • related: 指可能提供額外上下文的相關資源。
  • alternate: 指資源的替代版本。
  • describedby: 指描述當前資源的資源（例如，文件）。
  • type: 指示連結資源的媒體類型。
  • canonical: 指首選版本的資源。

有關註冊連結關係的完整列表，請參考 IANA 連結關係類型。

自定義 rel 的 CURIE 語法 ​

在定義自定義 rel 值時，可以使用通用 URI 參考標識符（CURIE）語法。CURIE 允許 URI 的緊湊表示，使定義自定義關係變得更容易。語法如下：

http
prefix:local-name

其中 prefix 是定義的命名空間，local-name 是特定的關係。例如：

http
myrel:customRelation

在這種情況下，myrel 將是一個映射到特定命名空間的前綴，允許客戶端理解自定義關係的上下文。

語法 ​

Link 標頭由一個或多個連結關係組成，每個連結關係由 URI 和可選的屬性集定義。一般語法如下：

http
Link: <URI>; rel="relation"; type="media-type"; title="title"

屬性 ​

  • rel: 指示當前文件與連結資源之間的關係。

  • type: 指定連結資源的媒體類型（例如，application/json）。

  • title: 提供連結資源的人類可讀標題。

示例 ​

以下是 HTTP 回應中的 Link 標頭示例：

http
Link: <https://api.example.com/users/1>; rel="self", <https://api.example.com/users/2>; rel="next", <https://api.example.com/custom>; rel="myrel:customRelation"

在此示例中，回應指示當前資源可以在 https://api.example.com/users/1 訪問，序列中的下一個資源是 https://api.example.com/users/2，並且定義了一個自定義關係 myrel:customRelation。

用例 ​

  1. 分頁: Link 標頭通常用於 API 中，以通過提供指向下一頁和上一頁結果的連結來促進分頁。

  2. 資源關係: 它可以用來指示資源之間的關係，例如層次數據中的父子關係。

設計思考 ​

Hypermedia API（HATEOAS）可以取代 Link 標頭的作用，因此在某些 API 規範中，如果它已經宣稱支援 HATEOAS，Link 標頭可能會被禁用。然而，因為我們不建議使用 HATEOAS，Link 標頭的重要性因此增加。

相關標準 ​