分享

浅谈RESTful API设计风格

 海拥 2021-11-30

关于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类型的操作,等等。但是,基于开发人员的使用习惯,甚至某些复杂的业务可能包含增删改查中的多种数据操作,无法准确的定义这到底是哪一种操作,所以,常规做法依然只使用POSTGET这2种请求方式,并不使用PUTDELETE方式。

例如:以下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) {
}

    转藏 分享 献花(0

    0条评论

    发表

    请遵守用户 评论公约

    类似文章 更多