RESTful API设计实例

目录

基本架构

模拟实例

理论依据

实例

从属关系

并列关系

总结

API设计

代码与RESTful API

需求：用户组管理

创建/编辑用户组

删除用户组

列举用户组

规划数据集

把数据集划分为资源

用URI为资源命名

---

基本架构

若待定义的数据类型可由其他数据组合而成，则直接使用allOf，如下图所示。

若数据有多重描述形式，使用多态（oneOf），如下图所示。

模拟实例

理论依据

url是数据的地址，json是数据的描述，数据之间存在从属和并列关系

实例

有一个文件表file

从属关系

表file的从属数据是文件总数items_count，所有文件items，items的从属数据是每个文件的数据item
在url中的表现：斜杠分隔的层级关系，/file/items_count，/file/items，/file/items/item1,item2
在json中的表现：file object内包含items_count和items字段，items array内包含item1,item2元素

并列关系

表file中的items_count和items，items中的各个item之间
在url中的表现：逗号分隔的并列关系，/file/items_count,items，/file/items/item_id1,item_id2
在json中的表现：file object中items_count和items字段，items array中item1,item2元素

总结

1. 数据之间的从属与并列关系，均可以通过数据的唯一标识即预定义的名字（object中字段的key）或随机生成的id（array中元素的id），在url和json中表达，即object中字段的key和array中元素的id，均可出现在url和json中
2. 并列关系的数据，即数据的集合，可用json中的object或array表示

API设计

获取所有信息

get /file
或
get /file/items_count,items
{
    "items_count": 2,
    "items": [
        {
            "id": 1,
            "parent_id": "xxxx",
            "name": "item1"
        },
        {
            "id": 2,
            "parent_id": "yyyy",
            "name": "item2"
        }
    ]
}

获取文件总数

get /file/items_count
{
    "items_count": 2,
}

获取所有文件

get /file/items
{
    "items": [
        {
            "id": 1,
            "parent_id": "xxxx",
            "name": "item1"
        },
        {
            "id": 2,
            "parent_id": "yyyy",
            "name": "item2"
        }
    ]
}
或
[
    {
        "id": 1,
        "parent_id": "xxxx",
        "name": "item1"
    },
    {
        "id": 2,
        "parent_id": "yyyy",
        "name": "item2"
    }
]

获取文件1

get /file/items/1
{
    "id": 1,
    "parent_id": "xxxx",
    "name": "item1"
}
或
认为获取单个是获取多个的特例
[
    {
        "id": 1,
        "parent_id": "xxxx",
        "name": "item1"
    }
]

获取文件1，文件2

get /file/items/1,2
[
    {
        "id": 1,
        "parent_id": "xxxx",
        "name": "item1"
    },
    {
        "id": 2,
        "parent_id": "yyyy",
        "name": "item2"
    }
]

代码与RESTful API

RESTful API的设计思路和面向对象的程序设计类似

需求：用户组管理

创建/编辑用户组

用户组包含以下信息：

名称	必填	可编辑	备注
组名	Y	Y	用户组唯一，不能包含 空格 或 \ / : * ? " < > | 特殊字符, 长度不能超过128个字符。
备注	N	Y	0-255个字符，不限制字符类型。

• 组名必须用户组唯一，组名重复时创建/编辑失败并报错。
• 编辑不存在的用户组，保存时应当失败并报错。

删除用户组

如果被删除的用户组不存在，逻辑上认为删除成功，但不需要记录删除日志。

列举用户组

• 支持分页列举用户组。
• 支持根据用户组名称搜索用户组。
• 排序规则：按组名和创建时间排序，默认按创建时间降序排序（最新创建在最前）。

规划数据集

根据需求，确定服务内包含哪些数据，类似代码中定义结构体或者类

// 用户组功能有两个表
// 组相关信息
type group struct{
	id string       // 组ID
	name string     // 组名
	notes string    // 备注
}

// 组成员
type groupMember struct{
	id string        // 成员ID
	group_id string  // 组ID
	type string      // 成员类型：user、department
}

把数据集划分为资源

数据集划分为资源，类似代码中的实例化对象

var groups map[string]group
var groupMemebers map[string][string]groupMember

用URI为资源命名

对象的名字即为URL，如果设计出来的url很复杂或者设计比较困难，那么需要考虑数据集规划是否合理

// 所有用户组
var groups map[string]group
// URL
/groups

// 某一用户组
groups[id]
// URL
/groups/{id}


// 某一用户组的特定信息：name，notes
groups[id].name
groups[id].notes
// URL
/groups/{id}/{fields} // fields可以为name或者remark或者两者组合，用逗号分隔

// 所有用户组成员
var groupMemebers map[string][string]groupMember
// URL
/group-members


// 某一用户组所有成员
groupMembers[groupID]
// URL
/group-members/{group_id}


// 某一用户组中某一成员
groupMembers[groupID][memberID]
// URL
/group-members/{group_id}/{member_id}


// 某一用户组中某些成员
groupMembers[groupID][memberID1]
groupMembers[groupID][memberID2]
// URL
/group-members/{group_id}/{member_ids} // member_ids为多个member_id的数组，用逗号分隔