API接口规范

目录

查询
条件查询
添加
删除
修改
- 局部修改
- 全量替换
多数据查询

在RESTful 规范的基础上，根据管理类型项目的开发经验，对API接口进行了定制化和规范化，以减少沟通成本，提高开发和维护效率。

除了对请求的方法和URL进行了规范，对请求的返回数据格式也进行了规范化。

查询

查询某个数据模型的全部数据列表

Method	GET
URL	http://{{server_url}}/api/v1.0/{url_prefix}/
Payload	-
Return	包含状态和数据列表/异常信息的json对象
	-成功	`{ "data": [ //数据列表 { "email": "admin@focus-ui.com", "id": 1, "name": "administrator", "role_id": 1, "status": "enable", "type": "local", "username": "admin" }, { "email": "test@focus-ui.com", "id": 2, "name": "abc", "phone": "", "role_id": 2, "status": "enable", "type": "local", "username": "test" } ], "status": "success" //状态，请求成功 }`
	-失败	`{ "message": "Unauthorized", //异常信息，未授权 "status": "fail", //状态，请求成功，但是处理异常 "status_code": "uri_unauthorized" //状态码 }`
备注	请求失败有两种情况请求失败，例如服务器异常/客户端错误等，这类异常是服务器没有catch住的，需要通过HTTP 响应代码进行判断处理请求成功，但处理失败，例如未授权，这类异常是服务器catch住的，可以通过请求结果返回的status/status_code进行判断处理，这里的status_code可用于客户端国际化

条件查询

包含分页、搜索、排序等的条件查询

Method	POST
URL	http://{{server_url}}/api/v1.0/{url_prefix}/pss/
Payload	分页/搜索/排序等查询条件
	`{ "search": {. //搜索/过滤条件，多个条件之间是 AND的关系 "like": "abc", //-模糊查询，匹配所有可供模糊查询的列中的字符串 "name": "cde" //-精确查询，完全匹配 }, "sort": { //排序条件 "field": "name", //-排序的属性 "order": "asc" //-排序的顺序，顺序asc或倒序desc }, "page": { //分页属性 "offset": 0, //-当前页数据的偏移数 "size": 20 //-当前页的数据数量 } }`
Return	包含状态和数据列表/异常信息的json对象
	-成功	{ "data": { //数据对象，添加了count属性 "count": 26, //符合条件的数据总数，可用于分页 "data": [ //数据列表 { "action": "add", "created_at": "Tue, 30 Mar 2021 15:57:56 GMT", "id": 3, "module": "template", "result": "success", "user_ip": "127.0.0.1", "user_name": "administrator", "username": "admin" }, { "action": "update", "created_at": "Tue, 30 Mar 2021 15:58:23 GMT", "id": 4, "module": "template", "result": "success", "user_ip": "127.0.0.1", "user_name": "administrator", "username": "admin" }, ……. ] }, "status": "success" //状态，请求成功 }
	-失败	`{ "message": "Unauthorized", //异常信息，未授权 "status": "fail", //状态，请求成功，但是处理异常 "status_code": "uri_unauthorized" //状态码 }`
备注	采用POST的方式，以更好的组织请求条件数据

添加

添加数据

Method	POST
URL	http://{{ server_url}}/api/v1.0/{url_prefix}/
Payload	要添加的json数据对象
	`{ "username": "taozh", "password": "123456", "name": "Zhang Tao", "email": "taozh@focus-ui.com", "role_id": 1 }`
Return	包含状态和添加成功以后的模型数据/异常信息的json对象
	-成功	`{ "data": { "created_at": "Mon, 12 Mar 2022 09:23:14 GMT", "email": "taozh@focus-ui.com", "id": 3, //生成的数据库ID，可用于删除/编辑等操作 "name": "Zhang Tao", "role_id": 1, "status": "enable", "type": "local", "updated_at": "Mon, 12 Mar 2022 09:23:14 GMT", "username": "taozh" }, "status": "success" //状态，请求成功 }`
	-失败	`{ "message": "Data Already Exists", //异常信息，数据已存在 "status": "fail", //状态，请求成功，但是处理异常 "status_code": "db_data_already_exist" //状态码 }`
备注

删除

删除指定的数据

Method	DELETE
URL	http://{{ server_url}}/api/v1.0/{url_prefix}/[pk_value]
Payload	-
Return	包含状态和删除成功以后的模型数据/异常信息的json对象
	-成功	`{ "data": { //被删除的数据信息 "created_at": "Mon, 14 Mar 2022 09:23:14 GMT", "email": "taozh@focus-ui.com", "id": 3, //可用于前端删除数据 "name": "Zhang Tao", "role_id": 1, "status": "enable", "type": "local", "updated_at": "Mon, 14 Mar 2022 09:23:14 GMT", "username": "taozh" }, "status": "success" //状态，请求成功 }`
	-失败	`{ "message": "Data Not Found", //异常信息，数据不存在 "status": "fail", //状态，请求成功，但是处理异常 "status_code": "db_data_not_found" //状态码 }`
备注	在URL中指定要删除的主键信息

修改

修改指定的数据，分为局部修改和全量替换

局部修改

只对传递的数据中指定的属性进行更新，数据中没有的属性保持不变

Method	PATCH
URL	http://{{ server_url}}/api/v1.0/{url_prefix}/
Payload	包含主键信息的要修改数据的json对象
	`{ "id":3, //要修改数据的主键 "password": "abcdef" //要修改的属性，除password以外的属性保持不变 }`
Return	包含状态和修改成功以后的模型数据/异常信息的json对象
	-成功	`{ "data": { //修改以后的数据信息 "created_at": "Mon, 14 Mar 2022 09:40:22 GMT", "email": "taozh@focus-ui.com", "id": 3, //可用于前端数据处理 "name": "Zhang Tao", "role_id": 1, "status": "enable", "type": "local", "updated_at": "Mon, 14 Mar 2022 09:49:38 GMT", "username": "taozh" }, "status": "success" //状态，请求成功 }`
	-失败	`{ "message": "Data Not Found", //异常信息，数据不存在 "status": "fail", //状态，请求成功，但是处理异常 "status_code": "db_data_not_found" //状态码 }`
备注	这里没有将主键放到URL中，主要是考虑到总会有Payload数据，所以将主键信息放到了Payload中，这是跟RESTful规范不同的地方，也可以完全按照RESTful规范，将主键放到URL中

全量替换

以替换的方式对数据进行替换，如果属性不存在则置空

Method	PUT
URL	http://{{ server_url}}/api/v1.0/{url_prefix}/
Payload	包含主键信息的要修改的全量数据json对象
	`{ "id": 3, //要修改数据的主键 "username": "taozh", //要修改数据的属性，如果属性不存在，则将数据库中对应的属性置空 "password": "abcdef", "name": "Tao Zhang", "email": "taozh@focus-ui.com", "role_id": 2 }`
Return	包含状态和修改成功以后的模型数据/异常信息的json对象
	-成功	`{ "data": { //修改以后的数据信息 "created_at": "Mon, 14 Mar 2022 09:40:22 GMT", "email": "taozh@focus-ui.com", "id": 3, "name": "Tao Zhang", "role_id": 1, "status": "enable", "type": "local", "updated_at": "Mon, 14 Mar 2022 09:49:38 GMT", "username": "taozh" }, "status": "success" //状态，请求成功 }`
	-失败	`{ "message": "Data Not Found", //异常信息，数据不存在 "status": "fail", //状态，请求成功，但是处理异常 "status_code": "db_data_not_found" //状态码 }`
备注	除非场景特殊，一般通过PATCH的方式进行更新即可

多数据查询

一次查询多个模型数据

Method	GET
URL	http://{{server_url}}/api/v1.0/{url_prefix}/query_multiple/
Payload	-
Return	包含状态和数据列表/异常信息的json对象
	-成功	{ "data": { //包含多个模型数据列表的数据对象 "roles": [ //模型数据列表A { "created_at": "Thu, 14 Jan 2021 12:19:27 GMT", "default": false, "description": "", "id": 1, "name": "Manager", "updated_at": "Fri, 15 Jan 2021 15:14:50 GMT" }, { "created_at": "Thu, 08 Apr 2021 10:02:25 GMT", "default": false, "description": "abc", "id": 2, "name": "Guest", "updated_at": "Tue, 26 Oct 2021 16:06:53 GMT" } ], "users": [ //某个模型数据列表B { "created_at": "Thu, 14 Jan 2021 12:19:27 GMT", "email": "admin@focus-ui.com", "id": 1, "name": "administrator", "role_id": 1, "status": "enable", "type": "local", "updated_at": "Thu, 10 Jun 2021 17:49:33 GMT", "username": "admin" }, { "created_at": "Thu, 08 Apr 2021 09:55:04 GMT", "description": "", "email": "test@focus-ui.com", "id": 2, "name": "abc", "phone": "", "role_id": 2, "status": "enable", "type": "local", "updated_at": "Thu, 18 Nov 2021 19:58:55 GMT", "username": "test" }, { "created_at": "Mon, 14 Mar 2022 09:40:22 GMT", "email": "taozh@focus-ui.com", "id": 3, "name": "Zhang Tao", "role_id": 1, "status": "enable", "type": "local", "updated_at": "Mon, 14 Mar 2022 09:49:38 GMT", "username": "taozh" } ] }, "status": "success" //状态，请求成功 }
	-失败	`{ "message": "Unauthorized", //异常信息，未授权 "status": "fail", //状态，请求成功，但是处理异常 "status_code": "uri_unauthorized" //状态码 }`
备注	主要是为了减少请求次数，方便前端使用