[译]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


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

[译]HAL-超文本应用语言的更多相关文章

  1. html 超文本标记语言

    1.html超文本标记语言 2.在html中存在着大量的标签,我们用html中存在的标签将要显示在网页的内容包含起来. 3.css 控制网页显示内容的效果. 4.html+css 只能是静态网页. 5 ...

  2. 超文本标记语言(HTML)

    超文本标记语言(HyperText MarkUp Language,HTML) HTML是用来制作网页的标记语言,HTML不需要编译,直接由浏览器解析: HTML文件是一个文本文件,包含了一些HTML ...

  3. HTML——超文本标记语言

    HTML: 网站(站点) - 网页 1.HTML作为文件后缀名,可以把文件变为网页 2.HTML是一门编程语言的名字:超文本标记语言 3.超越了文字的范畴,除了文字还可以有图片.视频.音频.动画特效等 ...

  4. html超文本标记语言的由来

    万维网上的一个超媒体文档称为一个页面:page,作为一个组织或者个人在万维网上放置开始点的页面称为主页:homepage或者首页,主页中通常有指向其他相关页面或者其他节点的指针,就是通常所说的超链接, ...

  5. HTML:Hyper Text Markup Language 超文本标记语言

    1.HTML是什么? *Hyper Text Markup Language 超文本标记语言 *Hyper Text:超链接.把不同空间的资源,整合在一起,形成逻辑上的网状结构. *Markup La ...

  6. 超文本标记语言HTML

    介绍html文档的基本结构,html常用标签的使用,理解html语言制作网页基本原理. html概述和基本结构 html概述 HTML是 HyperText Mark-up Language 的首字母 ...

  7. Html就是超文本标记语言的简写,是最基础的网页语言

    Html就是超文本标记语言的简写,是最基础的网页语言. Html是通过标签来定义的语言,代码都是由标签所组成. Html代码不用区分大小写. Html代码由<html>开始</htm ...

  8. html(HyperText Markup Language)--超文本标记语言

    1.html的简介? * 什么是html? ** HyperText Markup Language:超文本标记语言,网页语言 ** 超文本:超出文本的范畴,使用html可以轻松实现这样操作: ** ...

  9. HTML(超文本标记语言)的内容和理解

    由于上篇文章中提到WebMethod的Description 属性(propery)中可以使用超文本,因此就记录一篇关于超文本的文章以供参考,注意:Description=" HTML格式  ...

随机推荐

  1. Java基础 - 数据类型和运算符

    Java 语言支持的类型分为两类:基本数据类型(Primitive Type)和引用类型(Reference Type). 目录 基本数据类型 数值类型 整数类型 byte short int lon ...

  2. c# 使用Newtonsoft.Json解析JSON数组

    一.获取JSon中某个项的值 要解析格式: [{"VBELN":"10","POSNR":"10","RET_ ...

  3. 强化学习之二:Q-Learning原理及表与神经网络的实现(Q-Learning with Tables and Neural Networks)

    本文是对Arthur Juliani在Medium平台发布的强化学习系列教程的个人中文翻译.(This article is my personal translation for the tutor ...

  4. SFDC 401认证准备及考试

    401认证准备及考试 刚过了401的认证,一些个人的体会,希望能帮助到准备过401的朋友. 1. 考试只是手段,不是目的.这个链接的视频请认真看完,http://www.salesforcetrain ...

  5. 开发一个健壮的npm包

    项目地址:loan-calculate-utils npm包的发布.更新查看上一篇文章 开发一个基础的npm包 目前我们的目录是这个样子: . ├── source 源代码目录 │   └── ind ...

  6. 一、配置Ubuntu网络设置大纲

    root@ubuntu:为我的Ubuntu系统,即 用户名@主机名: 1.改主机名 ifconfig查询本机IP地址vim  /etc/hostname进入i编辑更改,改完按esc键 然后:wq!保存 ...

  7. Spring Boot熟稔于心的20个常识

    1.什么是 Spring Boot? Spring Boot 是 Spring 开源组织下的子项目,是 Spring 组件一站式解决方案,主要是简化了使用 Spring 的难度,简省了繁重的配置,提供 ...

  8. 一夜搞懂 | JVM 字节码执行引擎

    前言 本文已经收录到我的 Github 个人博客,欢迎大佬们光临寒舍: 我的 GIthub 博客 学习导图 一.为什么要学习字节码执行引擎? 代码编译的结果从本地机器码转变为字节码,是存储格式发展的一 ...

  9. 服务器部署Jupyter Notebook

    先安装jupyter notebook pip install ipython pip install jupyter 创建一个目录(jupyter notebook工作目录) mkdir jupyt ...

  10. 实际开发中 dao、entity的代码怎样自动生成?一款工具送给你

    01 关注"一猿小讲"朋友,都知道以往的文章一直倡导拒绝 CRUD,那到底什么是 CRUD?今天咱们就聊聊 Java 妹子小猿与数据库老头交互的事儿. 产品小汪铿锵有力的说:小猿同 ...