理解 RESTful API 设计规范
一、什么是REST?
REST这个词,是Roy Thomas Fielding在他2000年的博士论文中提出的。Fielding是一个非常重要的人,他是HTTP协议(1.0版和1.1版)的主要设计者、Apache服务器软件的作者之一、Apache基金会的第一任主席。
Fielding将他对互联网软件的架构原则,定名为REST,即Representational State Transfer的缩写。翻译是"表现层状态转化"。
它是基于HTTP、URI、XML、JSON等标准和协议,支持轻量级、跨平台、跨语言的架构设计。
二、REST设计原则:
需要符合如下的一些原则:
1. 每一个URI代表一种资源;
2. 同一种资源有多种表现形式(xml/json);
3. 所有的操作都是无状态的。
4. 规范统一接口。
5. 返回一致的数据格式。
6. 可缓存(客户端可以缓存响应的内容)。
三、什么是RESTful?
如果一个架构符合REST原则,就称它为RESTful架构。RESTful是目前最流行的API设计规范,通过一套统一的接口为所有web相关提供服务,实现前后端分离。
四、理解规范统一的接口
Rest接口约束定义为: 资源识别;请求动作;响应信息; 它表示通过uri表示出要操作的资源,通过请求动作(http method)标识要执行的操作,通过返回的状态码来表示这次请求的执行结果。
比如说,未使用Rest规范之前,我们可能有增删改查 等接口,会设计出类似这样的接口: /xxx/newAdd (新增接口), /xxx/delete(删除接口), /xxx/query (查询接口), /xxx/uddate(修改接口)等这样的。增删改查有四个不同的接口,维护起来可能也不好。
Restful规范,请求只需要一个接口,比如设计该接口为 /xxx/apis 这样的一个接口就可以了,然后请求方式(method)有 GET--查询(从服务器获取资源); POST---新增(从服务器中新建一个资源); PUT---更新(在服务器中更新资源),DELETE---删除(从服务器删除资源),PATCH---部分更新(从服务器端更新部分资源) 等这些方式来做,服务器端返回的数据也可以是相同的,只是我们前端会根据状态码来判断请求成功或失败的状态值来判断。
五、 URL及参数设计规范
1. url设计规范
1) url末尾不需要出现斜杠/
2) 在url中使用斜杠/是表达层级关系的。
3) 在uri中可以使用连接符-, 来提升可读性。
比如 http://xxx.com/xx-yy 比 http://xxx.com/xx_yy中的可读性更好。
4) 在url中不允许出现下划线字符_.
5) 在url中尽量使用小写字符。
6) 在url中不允许出现文件扩展名. 比如接口为 /xxx/api, 不要写成 /xxx/api.php 这样的是不合法的。
7) 在url中使用复数形式。
具体可以看:(https://blog.restcase.com/7-rules-for-rest-api-uri-design/)
在RESTful架构中,每个url代表一种资源,因此url设计中不能使用动词,只能使用名词,并且名词中也应该尽量使用复数形式。使用者应该使用相应的http动词 GET、POST、PUT、PATCH、DELETE等操作这些资源即可。
那么在我们未使用RESTful规范之前,我们是如下方式来定义接口的,形式是不固定的,并且没有统一的规范。比如如下形式:
http://xxx.com/api/getallUsers; // GET请求方式,获取所有的用户信息 http://xxx.com/api/getuser/1; // GET请求方式,获取标识为1的用户信息 http://xxx.com/api/user/delete/1 // GET、POST 删除标识为1的用户信息 http://xxx.com/api/updateUser/1 // POST请求方式 更新标识为1的用户信息 http://xxx.com/api/User/add // POST请求方式,添加新的用户
如上我们可以看到,在未使用Restful规范之前,接口形式是不固定的,没有统一的规范,下面我们来看下使用RESTful规范的接口如下,两者之间对比下就可以看到各自的优点了。
http://xxx.com/api/users; // GET请求方式 获取所有用户信息 http://xxx.com/api/users/1; // GET请求方式 获取标识为1的用户信息 http://xxx.com/api/users/1; // DELETE请求方式 删除标识为1的用户信息 http://xxx.com/api/users/1; // PATCH请求方式,更新标识为1的用户部分信息 http://xxx.com/api/users; // POST请求方式 添加新的用户
如上我们可以看到,增删改成我们都是使用同一个api接口,只是请求的方式 GET(查询)、POST(新增)、DELETE(删除)、PACTH(部分更新)来代表的是增删改查操作的方式。然后开发获取到该请求的header头部信息,就可以知道是什么方式来请求数据的了。
2. HTTP请求规范
GET (SELECT): 查询;从服务器取出资源.
POST(CREATE): 新增; 在服务器上新建一个资源。
PUT(UPDATE): 更新; 在服务器上更新资源(客户端提供改变后的完整资源)。
PATCH(UPDATE): 更新;在服务器上更新部分资源(客户端提供改变的属性)。
DELETE(DELETE): 删除; 从服务器上删除资源。
3. 参数命名规范
参数推荐采用下划线命名的方式。比如如下demo:
http://xxx.com/api/today_login // 获取今天登录的用户。 http://xxx.com/api/today_login&sort=login_desc // 获取今天登录的用户、登录时间降序排序。
六、 http状态码相关的
状态码范围
客户端的每一次请求, 服务器端必须给出回应,回应一般包括HTTP状态码和数据两部分。
1xx: 信息,请求收到了,继续处理。
2xx: 代表成功. 行为被成功地接收、理解及采纳。
3xx: 重定向。
4xx: 客户端错误,请求包含语法错误或请求无法实现。
5xx: 服务器端错误.
七、返回数据格式
RESTful规范中的请求应该返回统一的数据格式。对于返回的数据,一般会包含如下字段:
1) code: http响应的状态码。
2) status: 包含文本, 比如:'success'(成功), 'fail'(失败), 'error'(异常)
当status的值为 'fail' 或 'error'时,需要添加 message 字段,用于显示错误信息。
3) data: 当请求成功的时候, 返回的数据信息。 但是当状态值为 'fail' 或 'error' 时,data仅仅包含错误原因或异常信息等。
返回成功的响应JSON格式一般为如下:
返回失败的响应json格式为如下:
{
"code": 401,
"status": "error",
"message": '用户没有权限',
"data": null
}
参考链接:
https://www.cnblogs.com/tugenhua0707/p/12153857.html
http://www.ruanyifeng.com/blog/2011/09/restful.html