RESTful api设计风格
简介
REST(Representational State Transfer):表象层状态转变
RESTful对api进行规范和约束,使得api统一规范,增强api的可读性,便于开发。
设计原则
1、每一个URI代表一种资源
2、客户端通过四个HTTP动词(get、post、put、delete),对服务器端资源进行操作
因此,这种风格的接口url中没有动词,而是通过四个HTTP动词(get、post、put、delete)来代表动作。
Http动词
分别对应四种基本操作:
- GET用来获取资源
- POST用来新建资源(也可以用于更新资源)
- PUT用来更新资源
- DELETE用来删除资源
具体实施
版本控制
如github开放平台的API:http://developer.github.com/v3/ 可以发现,一般的项目加版本v1,v2,v3版本号,为的是兼容一些老版本的接口,这个加版本估计只有大公司大项目才会去使用。
参数命名规范
query parameter可以采用驼峰命名法,也可以采用下划线命名的方式,推荐采用下划线命名的方式,据说后者比前者的识别度要高,其中,做前端开发基本都后后者,而做服务器接口开发基本用前者。
http://example.com/api/users/today_login 获取今天登陆的用户 http://example.com/api/users/today_login&sort=login_desc 获取今天登陆的用户、登陆时间降序排列
url命名规范
API 命名应该采用约定俗成的方式,保持简洁明了。在RESTful架构中,每个url代表一种资源,所以url中不能有动词,只能有名词,并且名词中也应该使用复数。实现者应使用相应的Http动词GET、POST、PUT、PATCH、DELETE、HEAD来操作这些资源即可
不规范的的url,冗余没有意义,形式不固定,不同的开发者还需要了解文档才能调用。
http://example.com/api/getallUsers //GET 获取所有用户 http://example.com/api/getuser/1 //GET 获取标识为1用户信息 http://example.com/api/user/delete/1 //GET/POST 删除标识为1用户信息 http://example.com/api/updateUser/1 //POST 更新标识为1用户信息 http://example.com/api/User/add //POST添加新的用户
规范后的RESTful风格的url,形式固定,可读性强,根据users名词和http动词就可以操作这些资源。名词可以使用驼峰命令或者"_"分割
http://example.com/api/users //GET 获取所有用户信息 http://example.com/api/users/1 //GET 获取标识为1用户信息 http://example.com/api/users/1 //DELETE 删除标识为1用户信息 http://example.com/api/users/1 //Patch 更新标识为1用户部分信息,包含在div中 http://example.com/api/users //POST 添加新的用户
统一返回数据格式
对于合法的请求应该返回统一的数据格式,对于返回数据,通常会包含如下字段。
- code——即一个整数类型的HTTP响应状态码。
- message——即返回给前端的信息,正常返回时是"success",当值为 "fail" 或 "error" 时,用于显示错误信息。
- data——即前端需要返回的数据。 当值为 "fail" 或 "error" 时,设置为null。
返回成功的响应json格式:
{ "code": 200, "message": "success", "data": { "name": "小明", "age": 16, "sex": 0 } }
返回失败的响应json格式:
{ "code": 401, "message": "error message", "data": null }
http状态码
2**:成功–表示请求已被成功接收。
200(成功)用浏览器打开一个网页,正常情况下都会返回200HTTP状态码。
201(创建成功)代表资源创建成功
3**:重定向(URL跳转),要完成请求必须进行更进一步的操作。
300(多种选择)下载一部片,服务器有 avi、mp4 等格式。
301(永久移动)请求的网页已永久移动到新位置,自动将请求者转到新位置。
304 (页面未修改) :按F5刷新(第二次访问)。
4**:客户端错误,请求有语法错误或请求无法实现。
400(错误请求)服务器不理解请求的语法。
401(未授权)没有携带认证信息或携带了错误的认证信息,而没有通过认证。(未登录时)
403(禁止)携带了正确的认证信息,服务器认为该用户对该资源无权访问。(https输成了http)
404(未找到)请求的内容不存在。
5**:服务器端错误,服务器未能实现合法的请求。
500(服务器内部错误)服务器自己出现错误。
502(网关错误)服务器作为网关或代理,从上游服务器收到无效响应。
503(服务器不可用)服务器超载或停机维护不可用。
查询参数
在请求数据时,客户端经常会对数据进行过滤和分页等要求,而这些参数推荐采用HTTP Query Parameter的方式实现。
//搜索用户,最近登录 http://example.com/api/users?recently_login_day=3 //搜索用户,按照注册时间降序 http://example.com/api/users?sort=register_time_desc //搜索用户,按照注册时间升序、活跃度降序 http://example.com/api/users?sort=register_time_asc,liveness_desc
复杂参数
xxx
后端案例
GET请求
## url路径传参1
http://localhost:8080/api/user?id=1
后端要获取code参数,可以使用@RequestParam注解
## url路径参数2
http://localhost:8080/api/user/1
后端使用@PathVariable可以接收路径参数1。
POST请求
## Headers传值
在这里我们把Content-Type设置为了json格式。
我们还可以在headers里面加入别的参数,比如token。
![](https://img2018.cnblogs.com/i-beta/1724295/202001/1724295-20200124021734982-1063296807.png)
后端可以通过HttpServletRequest获取请求头的内容,如:
request.getHeader(string name)
request.getHeaders(String name)
request.getHeaderNames()
### Body传值
一般来说,使用json格式传值,如下图:
![](https://img2018.cnblogs.com/i-beta/1724295/202001/1724295-20200124021754838-1461056284.png)
后端接受这种数据应该采用@RequestBody
@PostMapping(value = "/user")
public ApiResult addUser(@RequestBody UserDTO userDTO) {
return userService.add(userDTO);
}