浅谈RESTful API设计风格
关于RESTful API
相关资料:
RESTFUL是一种网络应用程序的设计风格和开发方式,基于HTTP,可以使用XML格式定义或JSON格式定义。RESTFUL适用于移动互联网厂商作为业务使能接口的场景,实现第三方OTT调用移动网络资源的功能,动作类型为新增、变更、删除所调用资源。
值得注意的是REST并没有一个明确的标准,而更像是一种设计的风格。
重点:RESTful是一种URL的设计风格。
解读:RESTful并没有严格的语法约定,不存在“必须满足什么条件才算是RESTful”,也并不是“不满足什么条件就一定不是RESTful”。通常,使用RESTful风格的API,响应给客户端的数据是XML或JSON格式的,也就是“响应正文”,是使用了前后端分离的开发方式。
在RESTful架构中,浏览器使用POST,DELETE,PUT和GET四种请求方式分别对指定的URL资源进行增删改查操作。因此,RESTful是通过URI实现对资源的管理及访问,具有扩展性强、结构清晰的特点。
解读:RESTful建议针对不同操作,使用不同的请求类型,例如“注册”的核心是插入用户数据,应该使用POST
类型的请求方式,而“修改密码”的核心是更新数据,应该使用PUT
类型的操作,等等。但是,基于开发人员的使用习惯,甚至某些复杂的业务可能包含增删改查中的多种数据操作,无法准确的定义这到底是哪一种操作,所以,常规做法依然只使用POST
和GET
这2种请求方式,并不使用PUT
和DELETE
方式。
例如:以下URL就可以视为RESTful风格的:
https://blog.csdn.net/x541211190/article/details/81141459
https://blog.csdn.net/wl_1013/article/details/81049691
其实,RESTful风格有一个非常典型的特征:将核心参数直接作为URL的一部分,而不是作为参数来传递!
如果不采取RESTful风格,以上的URL可能需要设计为:
https://blog.csdn.net/article/details/?username=x541211190&id=81141459
https://blog.csdn.net/article/details/?username=wl_1013&id=81049691
使用RESTful风格,可以使得URL更加简洁,更加易于阅读或理解!
以上示例只是csdn
是这样设计的,把URL中域名之后的第1级固定为“用户名”,在details
之后的固定为id
值,并不代表其它网站都必须这样设计,甚至其它几乎都不是这么设计的,所以,到底怎么设计URL,取决于开发人员对URL的理解,RESTful本身并没有作为相关约定!
如果没有明确的约定,可以采取以下风格:
/resources/id/command
或
/resouces/id/property/command
以上设计风格中:
- resources:资源,也就是需要访问的是哪种数据;
- id:数据的唯一标识,如果需要访问的数据只有1条,且id需要公开,则添加;
- property:要访问的某条数据的哪个属性;
- command:需要将某条数据或某条数据的属性执行哪种操作。
例如,可以设计为:
/users/password/change
/addresses/10/set_default
注意:如果将某参数值放在URL中,该参数一定是具有“唯一”特性的,否则,就不应该将该参数值放在URL中。
SpringMVC框架是支持RESTful风格的!在设计请求路径时,如果请求路径中包含某个可变的参数值,使用{}
框住自定义的名称即可,例如设计为:
@RequestMapping("{aid}/set_default")
在处理请求的方法的参数列表中,通过@PathVariable
注解即可获取到URL中占位符对应的值:
@RequestMapping("{aid}/set_default")
public JsonResult<Void> setDefault(@PathVariable("aid") Integer aid) {
}