RESTful API设计实例

目录

基本架构

模拟实例

理论依据

实例

从属关系

并列关系

总结

API设计

代码与RESTful API

需求:用户组管理

创建/编辑用户组

删除用户组

列举用户组

规划数据集

把数据集划分为资源

用URI为资源命名


基本架构

RESTful API设计实例_第1张图片RESTful API设计实例_第2张图片

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

RESTful API设计实例_第3张图片

若数据有多重描述形式,使用多态(oneOf),如下图所示。

RESTful API设计实例_第4张图片

模拟实例

理论依据

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的数组,用逗号分隔

你可能感兴趣的:(爱数技术专栏,restful,javascript,后端)