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: '[email protected]',
    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: '[email protected]',
    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: '[email protected]',
    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: '[email protected]',
    twitter: '@lvjian700'
}

获取复杂数据

{
    _links: {
        self: {
            href: 'http://userservices_host/users/lvjian700'
        }
    }
    id: 'lvjian700'
    name: 'lvjian',
    email: '[email protected]',
    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'
        }]
    }
}

参考资料

• Microservices
• Richardson Maturity Model
• HAL Primer
• HAL Specification
• HAL format specification