Restful接口设计

[概述] REST是指表现层状态转移(Representational State Transfer). 该概念首次出现在2000年Roy Fielding的博士论文中，Roy Fielding是HTTP规范的主要编写者之一. 其中，表现层是资源的表现层，对于网络中的资源就需要URI来定位.

Protocol

1.通信协议

• HTTP协议: 用于无安全性要求的场景。如内部服务器间调用，公司内部系统等。
• HTTPS协议: 用于有安全性要求的场景。https较http的效率低，但ssl证书使得https的数据传输较http更安全。

2.接口版本

• 风格一: http://api.demo.com/v1/posts，该风格的接口存在跨域问题，适用于SOA架构的项目(较大的项目)
• 风格二: http://www.demo.com/api/v1/posts，该风格的接口无跨域问题，适用于单一架构的项目(小型项目)

[注] 强烈推荐使用v加版本号的形式进行接口版本的控制，版本号使用简单数字，如v2。这样有利于接口升级和降级。

Request

1.请求方法(动词)

常用方法(动词/动作)	说明	常用方法(动词/动作)	说明
GET	获取资源	POST	新增资源
PUT	更新资源	DELETE	删除资源
PATCH	全量更新(除主键外全更新)	...

[说明] Restful风格中，请求的具体行为动作使用动词表示，动词由HTTP方法提供（即请求方法）。

2.请求路径(名词)

HTTP方法(指定动词)	请求路径(指定名次)	说明
GET	/users /users/posts	(根资源的访问) 获取所有用户的用户信息 (子资源的访问) 获取所有用户的文章信息
GET	/users/10 /users/10/posts	(根资源的访问) 获取id为10的用户的用户信息 (子资源的访问) 获取id为10的用户的文章信息
POST	/users	新增用户信息
PUT	/users/10	更新id为10的用户信息
DELETE	/users/10	删除id为10的用户信息
PATCH	/users/10	部分更新id为10的用户信息

[说明] Restful风格中，资源的定位使用名词表示，名词需手动规定（即URL路径）。名词不要单复数混用，建议全部使用复数形式。Restful的核心是资源，URL路径只应标识资源，所以应使用名词，而不是动词。

3.查询参数(集合)

查询功能	示例	说明
过滤Filtering	GET /users/posts?tag=python	查询tag为python的文章
排序Sorting	GET /users/posts?sort=+title,-id GET /users/posts?sort=title_asc,id_desc	查询到的文章按标题升序、id降序的方式排序
分页Pagination	GET /posts?page=5&size=20	查询第5页文章数据，每页查50条

[说明] Restful风格中，仅将查询字符串用于查询功能，通过查询参数指定查询条件。

Response

1.状态码

状态码	请求方法	说明信息(英文)	说明信息(中文)
200	GET	OK	成功获取资源
201	POST、PUT、PATCH	CREATED	成功创建或修改资源
204	DELETE	NO CONTENT	成功删除资源
400	ALL	Bad Request	请求错误，如GET参数有问题/PUT提交的数据错误等
401	ALL	Unauthorized	权限未通过认证
403	ALL	Forbidden	有权限都禁止访问该资源
404	ALL	Not Found	请求的资源不存在
500	ALL	Internal Server Error	服务器端错误

2.错误处理

• 方法一: 通过仅返回错误信息的方式实现错误处理，错误信息不为空就是有错误.

{
    "error": "User Not Found"
}

• 方法二: 通过返回更详细的错误信息来实现错误处理，甚至更详细的信息可以通过code查阅文档(通常错误为0表示无错误).

{
    "code": 10056,
    "message": "Invalid ID",
    "description": "More details"
}

3.响应结果

HTTP方法	请求路径	说明
GET	/users	获取所有用户的用户信息，返回JSON对象列表
GET	/users/10	获取id为10的用户的用户信息，返回查到的JSON对象
POST	/users	新增用户信息，返回新增的JSON对象
PUT	/users/10	更新id为10的用户信息，返回修改后的JSON对象
DELETE	/users/10	删除id为10的用户信息，返回空JSON对象
PATCH	/users/10	部分更新id为10的用户信息，返回修改后的JSON对象