[譯]HAL-超文字應用語言

東溪陳姓少年發表於2020-04-18

[譯]HAL-超文字應用語言

精益超媒體型別

總結

HAL 是一種簡單的格式，它提供了一種一致且簡便的方法在 API 的資源之間進行超連結。

採用 HAL 將使您的 API 易於探索，並且其文件很容易從 API 本身中發現。簡而言之，這將使您的 API 更易於使用，因此對客戶端開發人員更具吸引力。

使用適用於大多數程式語言的開源庫，可以輕鬆提供和使用採用HAL的API。它也很簡單，您可以像處理其他JSON一樣處理它。

一般描述

HAL提供了一組約定以JSON或XML表示超連結。（HAL文件的其餘部分只是普通的舊JSON或XML。）

不要使用臨時結構，也不要花費寶貴的時間來設計自己的格式；您可以採用HAL的約定，並專注於構建和記錄構成API的資料和轉換。

HAL 有點像計算機的 HTML，因為它是通用的，旨在通過超連結驅動許多不同型別的應用程式。不同的是，HTML 具有幫助"人工參與者"通過 Web 應用程式實現其目標的功能，而 HAL 旨在幫助"自動參與者"通過 Web API 實現其目標。

話雖如此，HAL實際上也非常人性化。其約定使 API 的文件可以從 API 訊息本身發現。這使得開發人員能夠直接進入基於 HAL 的 API 並探索其功能，而無需將一些外部文件對映到其旅程的認知開銷。

例子

下面的示例是如何使用 hal_json 表示訂單集合。需要查詢的事項：

  • 使用自連結(self)表示的主要資源的 URI（"/orders"）
  • 指向下一頁訂單的"next"連結
  • 名為"ea:find"的模板化連結，用於按 id 搜尋訂單
  • 陣列中包含多個“ ea:admin”連結物件
  • 訂單集合的兩個屬性； “currentlyProcessing（當前正在處理）”和“shippedToday（今天發貨）”
  • 具有自己的連結和屬性的嵌入式訂單資源
  • 名為"ea"的緊湊型 URI （curie） 用於擴充套件指向其文件 URL 的連結的名稱

application/hal+json

{
    "_links": {
        "self": { "href": "/orders" },
        "curies": [{ "name": "ea", "href": "http://example.com/docs/rels/{rel}", "templated": true }],
        "next": { "href": "/orders?page=2" },
        "ea:find": {
            "href": "/orders{?id}",
            "templated": true
        },
        "ea:admin": [{
            "href": "/admins/2",
            "title": "Fred"
        }, {
            "href": "/admins/5",
            "title": "Kate"
        }]
    },
    "currentlyProcessing": 14,
    "shippedToday": 20,
    "_embedded": {
        "ea:order": [{
            "_links": {
                "self": { "href": "/orders/123" },
                "ea:basket": { "href": "/baskets/98712" },
                "ea:customer": { "href": "/customers/7809" }
            },
            "total": 30.00,
            "currency": "USD",
            "status": "shipped"
        }, {
            "_links": {
                "self": { "href": "/orders/124" },
                "ea:basket": { "href": "/baskets/97213" },
                "ea:customer": { "href": "/customers/12369" }
            },
            "total": 20.00,
            "currency": "USD",
            "status": "processing"
        }]
    }
}

HAL 型號

HAL約定圍繞著代表兩個簡單的概念：資源和連結。

資源

資源具有：

  • 連結（到 URI）
  • 嵌入式資源（即其中包含的其他資源）
  • 狀態（沼點標準 JSON 或 XML 資料）

連結

連結有：

  • 目標（URI）
  • 關係，又名。"rel" （連結的名稱）
  • 其他一些可選屬性，以幫助棄用、內容協商等。

下面的影像大致說明了HAL表示的結構：

https://i.iter01.com/images/8be0bb506c77e56a9454b142baf3a3c57e52c6c196804253efe6f1d1b454d9de.jpg

HAL 在 API 中的使用方式

HAL 旨在構建 API，其中客戶端通過以下連結圍繞資源進行導航。

連結通過連結關係標識。連結關係是超媒體 API 的命脈：它們是告訴客戶端開發人員哪些可用資源以及如何與其互動的方式，它們就是它們編寫的程式碼將如何選擇要遍歷的連結。

但是，連結關係不僅僅是HAL中的標識字串。 它們實際上是URL，開發人員可以遵循這些 URL 來讀取給定連結的文件。 這就是所謂的“可發現性”。 這樣的想法是，開發人員可以輸入您的API，通讀可用連結的文件，然後通過API進行操作。

HAL鼓勵將連結關係（rel）用於：

  1. 識別表示中的連結和嵌入資源
  2. 推斷目標資源的預期結構和意義
  3. 向目標資源發出哪些請求和表示訊號

如何為 HAL 服務

HAL 具有 JSON 和 XML 變體的介質型別，其名稱是和分別。application/hal+json和application/hal+xml

在 HTTP 上提供 HAL 時，響應應包含相關的媒體型別名稱。Content-Type

HAL 文件的結構

最低有效檔案

HAL 文件必須至少包含空資源。

空的 JSON 物件：

{}

資源

在大多數情況下，資源應具有自己的URI

通過"self"連結表示：

{
    "_links": {
        "self": { "href": "/example_resource" }
    }
}

連結

連結必須直接包含在資源中：

連結表示為包含在雜湊中的 JSON 物件，該雜湊必須是資源物件的直接屬性：_links

{
    "_links": {
        "next": { "href": "/page=2" }
    }
}

連結關係

連結有關係（又名）。"rel"）。這表示特定連結的語義 - 含義。

連結 rels 是區分資源連結的主要方法。

它基本上只是雜湊中的一個鍵，將連結含義（"rel"）與包含資料（如實際"href"值）的連結物件相關聯：_links

{
    "_links": {
        "next": { "href": "/page=2" }
    }
}

API 可發現性

連結關係rels 應該是顯示有關給定連結的文件的 URL，使它們"可發現"。URL 通常相當長，並且有點討厭用作金鑰。為了繞過這一點，HAL 提供了"CURIEs"，它們基本上是名為令牌，您可以在文件中定義，並用於以更友好、更緊湊的方式表達連結關係 URI,例如ex:widget 而不是http://example.com/rels/widget。詳細資訊可在稍下一點的"CURIEs"部分中提供。

表示具有相同關係的多個連結

資源可能有多個共享同一連結關係的連結。

對於可能具有多個連結的連結關係，我們使用連結陣列。

{
    "_links": {
      "items": [{
          "href": "/first_item"
      },{
          "href": "/second_item"
      }]
    }
}

注：如果您不確定連結是否應是單數，則假定該連結是多個連結。如果選擇單數並發現需要更改它，則需要建立新的連結關係或面對斷開現有客戶端。

CURIEs

"CURIEs"幫助提供指向資源文件的連結。

HAL 為您提供了一個保留的連結關係"curies"，您可以使用它來提示資源文件的位置。

"_links": {
  "curies": [
    {
      "name": "doc",
      "href": "http://haltalk.herokuapp.com/docs/{rel}",
      "templated": true
    }
  ],

  "doc:latest-posts": {
    "href": "/posts/latest"
  }
}

"curies"部分中可以有多個連結。它們帶有一個"name"和模板化的"href"，其中必須包含佔位符。{rel}

然後，連結可以在其“ rel”之前加上curies的名稱。將latest-posts連結與doc文件curies關聯，將導致連結“ rel”設定為doc:latest-posts。

若要檢索有關資源的文件，客戶端將擴充套件關聯的 curies 連結與實際連結的"rel"。這將導致一個 URL，該 URL 應返回有關此資源的文件latest-posts ： http://haltalk.herokuapp.com/docs/latest-posts。

原文地址：http://stateless.co/hal_specification.html

關注筆者公眾號，推送各類原創/優質技術文章 ⬇️
image-20200410104030284

相關文章