实时专题:[译]HAL-超文本应用语言

admin 1个月前 (04-18) 科技 21 0

[译]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示意的结构:

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

关注笔者民众号,推送各种原创/优质技术文章 ⬇️

,

Sunbet

Sunbet www.yingerchevip.com Sunbet致力打造完美娱乐平台,为客户提供精彩绝伦的娱乐体验,各种娱乐方式让您大开眼界。sunbet等着你!

阳光在线声明:该文看法仅代表作者自己,与本平台无关。转载请注明:实时专题:[译]HAL-超文本应用语言

站点信息

  • 文章总数:164
  • 页面总数:0
  • 分类总数:8
  • 标签总数:251
  • 评论总数:107
  • 浏览总数:7406

标签列表