 hal-resource.png
HAL(Hypertext Application Language)是一個(gè)簡(jiǎn)單的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這種類(lèi)型的數(shù)據(jù)交換格式.
HAL支持xml和json兩種格式，本文將討論HAL+json格式.
HAL是什么樣 ?
舉個(gè)栗子, 我們?cè)O(shè)計(jì)一個(gè)獲取user信息的api接口:
沒(méi)接觸過(guò)HAL時(shí)，不出意外，我們會(huì)將API設(shè)計(jì)成這樣:
獲取用戶(hù)詳情
GET - /users/lvjian700
Content-Type: application/json
{
id: 'lvjian700',
name: 'lvjian',
email: 'useremail@email.com',
twitter: '@lvjian700'
}
獲取用戶(hù)列表
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格式
獲取用戶(hù)詳情
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.
獲取用戶(hù)列表
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: { //用于描述依賴(lài)資源。users提供了當(dāng)前我們想要的列表信息。
users: [{
_links: {
self: {
href: '/users/lvjian700' //訪(fǎng)問(wèn)這個(gè)link我們可以獲取用戶(hù)詳情
}
}
id: 'lvjian700'
name: 'lvjian',
},{
_links: {
self: {
href: '/users/meimei'
}
}
id: 'meimei'
name: 'meimei',
}]
}
}
為什么我們需要采用HAL這種格式描述api
回想一下Web Service的發(fā)展:
- 剛開(kāi)始我們采用SOAP協(xié)議提供web service, action和data使用xml包裝起來(lái)，采用HTTP POST發(fā)送請(qǐng)求。這種API非常笨重，已經(jīng)不再是首選的Web Service技術(shù).
- 之后REST-ful Web Service橫空出世，將數(shù)據(jù)描述為resource(URI)，采用最基本HTTP動(dòng)作(GET POST PUT DELETE)進(jìn)行訪(fǎng)問(wèn)，大多數(shù)時(shí)候采用json格式進(jìn)行數(shù)據(jù)交互，這種易讀，輕便的方式幾乎統(tǒng)治了互聯(lián)網(wǎng)API的架構(gòu)方式。
- 基于REST-ful Web Service發(fā)展出來(lái)的Micro Service, 又給架構(gòu)方式提出了新的挑戰(zhàn)。
在REST-ful Web Service的世界里:
- 我們使用resource(URI)描述API接口
- 我們使用Http verbs(GET, POST, PUT, DELETE)訪(fǎng)問(wèn)API
- 采用plain json作為數(shù)據(jù)交互格式
HAL的出現(xiàn)，主要彌補(bǔ)plain json在A(yíng)PI交互中的不足.讓plain json更具有描述性，更具有導(dǎo)航性.
在Micro Service的世界里，我們將大的系統(tǒng)拆分成小微小的API, 在將API組合起來(lái)為系統(tǒng)提供服務(wù)。
 micro_services.png
關(guān)于mirco service的可以在《Microservices》中了解更多.
在組合API時(shí)， plain json這種缺乏描述性的json格式缺陷現(xiàn)的非常明顯。我們要為API編寫(xiě)文檔，要為API之間的數(shù)據(jù)關(guān)系，交互方式提供說(shuō)明.
如果我們用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信息從哪來(lái)，location信息從哪里來(lái). 很清楚的知道location embedded in user.
關(guān)于描述API model模型，在《Richardson Maturity Model》中有更深入的討論
如何使用HAL+json描述常見(jiàn)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: { //用于描述依賴(lài)資源。users提供了當(dāng)前我們想要的列表信息。
users: [{
_links: {
self: {
href: '/users/lvjian700' //訪(fǎng)問(wèn)這個(gè)link我們可以獲取用戶(hù)詳情
}
}
id: 'lvjian700'
name: 'lvjian'
},{
_links: {
self: {
href: '/users/meimei'
}
}
id: 'meimei'
name: 'meimei'
}]
}
}
參考資料
|
