HAL(Hypertext Application Language)是一個(gè)簡單的API數(shù)據(jù)格式.它以xml和json為基礎(chǔ)谷婆，讓API變的可讀性更高么鹤，并且具有discoverable的特性.當(dāng)我們拿到HAL API返回的數(shù)據(jù)時(shí)粱坤，我們將會(huì)很容易根據(jù)當(dāng)前數(shù)據(jù)查找與其相關(guān)的數(shù)據(jù)朋魔。在Micro Service API設(shè)計(jì)中淹仑，傾向于采用HAL這種類型的數(shù)據(jù)交換格式.
HAL支持xml和json兩種格式绢记，本文將討論HAL+json格式.
HAL是什么樣 ?
舉個(gè)栗子, 我們設(shè)計(jì)一個(gè)獲取user信息的api接口:
沒接觸過HAL時(shí)薪鹦，不出意外掌敬，我們會(huì)將API設(shè)計(jì)成這樣:
獲取用戶詳情
GET - /users/lvjian700
Content-Type: application/json
{
id: 'lvjian700',
name: 'lvjian',
email: 'useremail@email.com',
twitter: '@lvjian700'
}
獲取用戶列表
GET - /users
Content-Type: application/json
{
total: 10
page: 2
page_size: 2
rows: [{
id: 'lvjian700',
name: 'lvjian'
}, {
id: 'meimei',
name: 'meimei'
}]
}
為了讓API返回?cái)?shù)據(jù)更具有關(guān)聯(lián)性,我們使用HAL+json格式
獲取用戶詳情
GET - /users/lvjian700
Content-Type: application/hal+json
{
_links: {
self: {
href: '/users/lvjian700'
}
}
id: 'lvjian700'
name: 'lvjian',
email: 'useremail@email.com',
twitter: '@lvjian700'
}
這里多了_links屬性惯豆，其中有一個(gè)self.href其中的連接指向當(dāng)前user resource.
獲取用戶列表
GET - /users
Content-Type: application/hal+json
{
_links: {
self: {
href: '/users?page=2'
},
first: {
href: '/users'
},
prev: {
href: '/users?page=1'
}
next: {
href: '/users?page=3'
},
last: {
href: '/users?page=5'
}
},
count: 2
totoal: 10
_embedded: { //用于描述依賴資源。users提供了當(dāng)前我們想要的列表信息奔害。
users: [{
_links: {
self: {
href: '/users/lvjian700' //訪問這個(gè)link我們可以獲取用戶詳情
}
}
id: 'lvjian700'
name: 'lvjian',
},{
_links: {
self: {
href: '/users/meimei'
}
}
id: 'meimei'
name: 'meimei',
}]
}
}
為什么我們需要采用HAL這種格式描述api
回想一下Web Service的發(fā)展:
- 剛開始我們采用SOAP協(xié)議提供web service, action和data使用xml包裝起來楷兽，采用HTTP POST發(fā)送請求。這種API非常笨重华临，已經(jīng)不再是首選的Web Service技術(shù).
- 之后REST-ful Web Service橫空出世芯杀，將數(shù)據(jù)描述為resource(URI)，采用最基本HTTP動(dòng)作(GET POST PUT DELETE)進(jìn)行訪問雅潭，大多數(shù)時(shí)候采用json格式進(jìn)行數(shù)據(jù)交互揭厚，這種易讀，輕便的方式幾乎統(tǒng)治了互聯(lián)網(wǎng)API的架構(gòu)方式扶供。
- 基于REST-ful Web Service發(fā)展出來的Micro Service, 又給架構(gòu)方式提出了新的挑戰(zhàn)筛圆。
在REST-ful Web Service的世界里:
- 我們使用resource(URI)描述API接口
- 我們使用Http verbs(GET, POST, PUT, DELETE)訪問API
- 采用plain json作為數(shù)據(jù)交互格式
HAL的出現(xiàn)，主要彌補(bǔ)plain json在API交互中的不足.讓plain json更具有描述性椿浓，更具有導(dǎo)航性.
在Micro Service的世界里太援，我們將大的系統(tǒng)拆分成小微小的API, 在將API組合起來為系統(tǒng)提供服務(wù)。
關(guān)于mirco service的可以在《Microservices》中了解更多.
在組合API時(shí)扳碍， plain json這種缺乏描述性的json格式缺陷現(xiàn)的非常明顯提岔。我們要為API編寫文檔碱蒙，要為API之間的數(shù)據(jù)關(guān)系振亮，交互方式提供說明.
如果我們用HAL+json描述一個(gè)帶location屬性的user信息
{
_links: {
self: {
href: 'http://userservices_host/users/lvjian700'
}
}
id: 'lvjian700'
name: 'lvjian',
email: 'useremail@email.com',
twitter: '@lvjian700',
_embedded: {
location: {
_links: {
self: {
href: 'http://locationservices_host/locations/1'
}
},
id: 1,
state: 'shaanxi',
city: 'xi\'an'
}
}
}
我們可以很清楚的知道user信息從哪來坊秸，location信息從哪里來. 很清楚的知道location embedded in user.
關(guān)于描述API model模型褒搔，在《Richardson Maturity Model》中有更深入的討論
如何使用HAL+json描述常見API
獲取單條數(shù)據(jù)
{
_links: {
self: {
href: 'http://userservices_host/users/lvjian700'
}
}
id: 'lvjian700'
name: 'lvjian',
email: 'useremail@email.com',
twitter: '@lvjian700'
}
獲取復(fù)雜數(shù)據(jù)
{
_links: {
self: {
href: 'http://userservices_host/users/lvjian700'
}
}
id: 'lvjian700'
name: 'lvjian',
email: 'useremail@email.com',
twitter: '@lvjian700',
_embedded: {
location: {
_links: {
self: {
href: 'http://locationservices_host/locations/1'
}
}
id: 1,
state: 'shaanxi',
city: 'xi\'an'
},
contacts: [{
_links: {
self: {
href: 'http://userservices_host/users/meimei'
}
},
id: 'meimei',
name: 'meimei
}, {
_links: {
self: {
href: 'http://userservices_host/users/jay'
}
},
id: 'jay',
name: 'jay'
}]
}
}
返回集合數(shù)據(jù)
{
_links: {
self: {
href: '/users?page=2'
},
first: {
href: '/users'
},
prev: {
href: '/users?page=1'
}
next: {
href: '/users?page=3'
},
last: {
href: '/users?page=5'
}
},
count: 2
totoal: 10
_embedded: { //用于描述依賴資源惧辈。users提供了當(dāng)前我們想要的列表信息。
users: [{
_links: {
self: {
href: '/users/lvjian700' //訪問這個(gè)link我們可以獲取用戶詳情
}
}
id: 'lvjian700'
name: 'lvjian'
},{
_links: {
self: {
href: '/users/meimei'
}
}
id: 'meimei'
name: 'meimei'
}]
}
}
