Microservices中的API设计 - HAL+Json API

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'
        }]
    }
}

参考资料

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 142,680评论 1 300
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 61,177评论 1 256
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 94,249评论 0 212
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 40,981评论 0 175
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 48,746评论 1 255
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 38,763评论 1 176
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 30,362评论 2 268
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 29,151评论 0 165
  • 想象着我的养父在大火中拼命挣扎,窒息,最后皮肤化为焦炭。我心中就已经是抑制不住地欢快,这就叫做以其人之道,还治其人...
    爱写小说的胖达阅读 28,964评论 6 229
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 32,501评论 0 213
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 29,285评论 2 215
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 30,614评论 1 229
  • 白月光回国,霸总把我这个替身辞退。还一脸阴沉的警告我。[不要出现在思思面前, 不然我有一百种方法让你生不如死。]我...
    爱写小说的胖达阅读 24,232评论 0 31
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 27,117评论 2 213
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 31,498评论 3 204
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 25,615评论 0 8
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 26,012评论 0 167
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 33,512评论 2 230
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 33,594评论 2 231

推荐阅读更多精彩内容