REST(Representation State Transfer,翻译为“表现层状态转化”)并非是一种技术或者规范,而是一种架构风格,这种架构风格逐渐被各种编程语言的web框架所支持。它包括了REST架构中如何标识资源,如何标识接口及操作的版本,如何标识操作接口及操作的版本,如何标识操作的结果等,主要内容如下:
1.使用“api”作为web上下文;
2.增加版本标识;
3,标识资源;
4.REST中的HTTP Method;
5.REST中的HTTP Status;
一、使用“api“作文上下文
建议使用”api“作为上下文,如:
http://192.168.0.1/api
也有的使用”api“作为二级域名:
http://api.xxxx.com
二、增加一个版本标识
http://192.168.0.1/api/v1.1
也有的做法是将版本信息放到HTTP头中,但这里推荐使用URL来体现,这样使得REST的相关代码更加容易阅读。
三、标识资源
将资源名放到URL中,如果资源中有层级关系,则放入层级关系:
http:192.168.0.1/api/v1.1/user
如果用户属于系统管理,也可以这么写:
http:192.168.0.1/api/v1.1/system/user
四、确定HTTP Method
在REST中,HTTP Method常常对应于以下含义:
*POST, 代表增加资源
*PUT,代表更改资源,客户端提供需完整的资源属性;
*GET,代表查询资源;
*PATCH,更新资源,客户端提供仅需要更改的资源属性
*DELETE,通常用于删除资源;
*HEAD,类似于GET,但仅仅只有HTTP头信息,头信息包含了需要查找的信息;
*OPTIONS:用于获取URI所支持的方法,响应信息会在HTTP头中包含一个名为”Allow“的头,值是所支持的方法,如”GET 、POST"
在业务系统中,删除往往并不是指的物理删除,而是逻辑删除,资源通常仍然在数据库中,值是状态设置为删除状态。
比如新增用户:
POST http://192.168.0.1//api/v1.1/system/user
查询用户id为451:
GET http://192.168.0.1//api/v1.1/system/user/451
查询所有用户:
GET http://192.168.0.1//api/v1.1/system/user
如果有翻页,可以在后面怎还offset、limit参数,比如:
GET http://192.168.0.1//api/v1.1/system/user?offset=1&limit=20&sortBy=name&sortOrder=desc
更新id为451用户:
PUT http://192.168.0.1//api/v1.1/system/user/451
删除id为451的用户:
DELETE http://192.168.0.1//api/v1.1/system/user/451
可以为资源标识添加后缀,使得REST代码更加容易阅读,比如:
GET http://192.168.0.1/api/v1.1/system/user451.json
返回id为451的用户信息,返回格式是json。
现在也有一种设计REST URI的方式,把操作也放到URI中,HTTP方法主要采用GET和POST,易于阅读。
五、确定HTTP Status
服务器向客户端返回HTTP Status以表示操作是否成功,常用的如下:
*200,ok,用户请求成功,如查询数据成功返回。
*400,错误的请求,在第三章中,URI匹配上springboot 中单额Controller,但方法参数匹配错误,就会抛出错误。
*404 NOT Found,用户发出的请求针对的资源不存在,通常是Spring Boot中的Controller没有匹配上URI,或者匹配上了Controller方法,但渲染的视图不存在
*405,用来访问本页面的HTTP Method不被允许,比如通过HTTP Get方法访问了一个@PostMapping的Controller方法
*406,表示无法使用请求的内容特性来相应请求的资源
*500,服务器内部错误,无法完成请求。