hal-resource.png
HAL(Hypertext Application Language)是一個簡單的API數據格式.它以xml和json為基礎，讓API變的可讀性更高，并且具有discoverable的特性.當我們拿到HAL API返回的數據時，我們將會很容易根據當前數據查找與其相關的數據。在Micro Service API設計中，傾向于采用HAL這種類型的數據交換格式.
HAL支持xml和json兩種格式，本文將討論HAL+json格式.
HAL是什么樣 ?
舉個栗子, 我們設計一個獲取user信息的api接口:
沒接觸過HAL時，不出意外，我們會將API設計成這樣:
獲取用戶詳情
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返回數據更具有關聯性,我們使用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屬性，其中有一個self.href其中的連接指向當前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提供了當前我們想要的列表信息。
users: [{
_links: {
self: {
href: '/users/lvjian700' //訪問這個link我們可以獲取用戶詳情
}
}
id: 'lvjian700'
name: 'lvjian',
},{
_links: {
self: {
href: '/users/meimei'
}
}
id: 'meimei'
name: 'meimei',
}]
}
}
為什么我們需要采用HAL這種格式描述api
回想一下Web Service的發展:
- 剛開始我們采用SOAP協議提供web service, action和data使用xml包裝起來，采用HTTP POST發送請求。這種API非常笨重，已經不再是首選的Web Service技術.
- 之后REST-ful Web Service橫空出世，將數據描述為resource(URI)，采用最基本HTTP動作(GET POST PUT DELETE)進行訪問，大多數時候采用json格式進行數據交互，這種易讀，輕便的方式幾乎統治了互聯網API的架構方式。
- 基于REST-ful Web Service發展出來的Micro Service, 又給架構方式提出了新的挑戰。
在REST-ful Web Service的世界里:
- 我們使用resource(URI)描述API接口
- 我們使用Http verbs(GET, POST, PUT, DELETE)訪問API
- 采用plain json作為數據交互格式
HAL的出現，主要彌補plain json在API交互中的不足.讓plain json更具有描述性，更具有導航性.
在Micro Service的世界里，我們將大的系統拆分成小微小的API, 在將API組合起來為系統提供服務。
micro_services.png
關于mirco service的可以在《Microservices》中了解更多.
在組合API時， plain json這種缺乏描述性的json格式缺陷現的非常明顯。我們要為API編寫文檔，要為API之間的數據關系，交互方式提供說明.
如果我們用HAL+json描述一個帶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.
關于描述API model模型，在《Richardson Maturity Model》中有更深入的討論
如何使用HAL+json描述常見API
獲取單條數據
{
_links: {
self: {
href: 'http://userservices_host/users/lvjian700'
}
}
id: 'lvjian700'
name: 'lvjian',
email: 'useremail@email.com',
twitter: '@lvjian700'
}
獲取復雜數據
{
_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'
}]
}
}
返回集合數據
{
_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提供了當前我們想要的列表信息。
users: [{
_links: {
self: {
href: '/users/lvjian700' //訪問這個link我們可以獲取用戶詳情
}
}
id: 'lvjian700'
name: 'lvjian'
},{
_links: {
self: {
href: '/users/meimei'
}
}
id: 'meimei'
name: 'meimei'
}]
}
}
