[译]HAL-超文本应用语言
[译]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)用于:
- 识别表示中的链接和嵌入资源
- 推断目标资源的预期结构和意义
- 向目标资源发出哪些请求和表示信号
如何为 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-超文本应用语言的更多相关文章
- html 超文本标记语言
1.html超文本标记语言 2.在html中存在着大量的标签,我们用html中存在的标签将要显示在网页的内容包含起来. 3.css 控制网页显示内容的效果. 4.html+css 只能是静态网页. 5 ...
- 超文本标记语言(HTML)
超文本标记语言(HyperText MarkUp Language,HTML) HTML是用来制作网页的标记语言,HTML不需要编译,直接由浏览器解析: HTML文件是一个文本文件,包含了一些HTML ...
- HTML——超文本标记语言
HTML: 网站(站点) - 网页 1.HTML作为文件后缀名,可以把文件变为网页 2.HTML是一门编程语言的名字:超文本标记语言 3.超越了文字的范畴,除了文字还可以有图片.视频.音频.动画特效等 ...
- html超文本标记语言的由来
万维网上的一个超媒体文档称为一个页面:page,作为一个组织或者个人在万维网上放置开始点的页面称为主页:homepage或者首页,主页中通常有指向其他相关页面或者其他节点的指针,就是通常所说的超链接, ...
- HTML:Hyper Text Markup Language 超文本标记语言
1.HTML是什么? *Hyper Text Markup Language 超文本标记语言 *Hyper Text:超链接.把不同空间的资源,整合在一起,形成逻辑上的网状结构. *Markup La ...
- 超文本标记语言HTML
介绍html文档的基本结构,html常用标签的使用,理解html语言制作网页基本原理. html概述和基本结构 html概述 HTML是 HyperText Mark-up Language 的首字母 ...
- Html就是超文本标记语言的简写,是最基础的网页语言
Html就是超文本标记语言的简写,是最基础的网页语言. Html是通过标签来定义的语言,代码都是由标签所组成. Html代码不用区分大小写. Html代码由<html>开始</htm ...
- html(HyperText Markup Language)--超文本标记语言
1.html的简介? * 什么是html? ** HyperText Markup Language:超文本标记语言,网页语言 ** 超文本:超出文本的范畴,使用html可以轻松实现这样操作: ** ...
- HTML(超文本标记语言)的内容和理解
由于上篇文章中提到WebMethod的Description 属性(propery)中可以使用超文本,因此就记录一篇关于超文本的文章以供参考,注意:Description=" HTML格式 ...
随机推荐
- Java多线程并发06——CAS与AQS
在进行更近一步的了解Java锁的知识之前,我们需要先了解与锁有关的两个概念 CAS 与 AQS.关注我的公众号「Java面典」了解更多 Java 相关知识点. CAS(Compare And Swap ...
- [C#] 命令总线模式
1 高内聚.低耦合 虽然已经毕业很多年了,但依然总是能记得,<软件工程>这门课的老师总是强调 "高内聚,低耦合". 这些年,在架构方面的技术发展方向,目标就是不断的拆分 ...
- Python - 面向对象(一)入门篇
Python里面有一句话:万物皆是对象 如何面向对象编程 设计类 创建类实例对象 实例对象调用方法 创建对象 在内存中为对象分配空间 调用初始化方法 __init__ 为对象初始化 对象创建后,内 ...
- VMware 虚拟机正在使用中
1.出现报错信息: 2.找到安装目录下面的.lck后缀文件夹(如有多个则全部删除) 3.删除此文件夹 4.成功开启虚拟机
- mpy开发物联网系列:1.mpy与服务器数据库方案
ini配置文件与非关系型数据库 在使用micropython开发esp32过程中,经常涉及到一些数据的配置读取,而esp32本身micropython难以安装很多数据库客户端的库,只能基于本地文件使用 ...
- [Docker02]Docker_registry
部署Docker仓库 Docker registry #检查端口5000是否被占用 netstat -tunlp | grep 5000 # the local host ip is 172.17.0 ...
- 【HDU2883】kebab——最大流
题目链接 把"时间粒子"作为最大流的计算结果 设置超级源点为 0 顾客点范围为 1 - 204 时间点 205 - 610 超级汇点 615 超级源点与所有顾客连线,容量为需求的烤 ...
- Keras实现RNN模型
博客作者:凌逆战 博客地址:https://www.cnblogs.com/LXP-Never/p/10940123.html 这篇文章主要介绍使用Keras框架来实现RNN家族模型,TensorFl ...
- OpenCV-Python 姿态估计 | 五十
目标 在本章中 我们将学习利用calib3d模块在图像中创建一些3D效果. 基础 这将是一小部分.在上一次相机校准的会话中,你发现了相机矩阵,失真系数等.给定图案图像,我们可以利用以上信息来计算其姿势 ...
- OpenCV-Python 直方图-4:直方图反投影 | 二十九
目标 在本章中,我们将学习直方图反投影. 理论 这是由Michael J. Swain和Dana H. Ballard在他们的论文<通过颜色直方图索引>中提出的. 用简单的话说是什么意思? ...