Restful入门


目录:

  1. Restful概念

  2. 具体规范

    2.1 格式规范

    2.2 协议

    2.3 域名

    2.4 版本

    2.5 名词应该使用复数

    2.6 URL中不能使用动词

    2.7 不符合CRUD的情况

    2.8 用HTTP动词表示对资源的操作

    2.9 HTTP状态码

    2.10 其它

参考/来源:

RESTful概念

在此之前,我们先聊聊什么是REST。REST实际上为Representational State Transfer的缩写,翻译为“表现层状态转化” 。如果一个架构符合REST 原则,就称它为RESTful架构。

  • Resource 资源

    REST忽略了主语,全称应该是资源的表现层状态转移。所谓资源就是互联网上的各种资源,比如文本、图片、音频、视频等。在互联网上通过URI指定唯一的资源,所谓的’上网‘就是通过调用资源的URL来跟互联网上的一系列资源进行互动。

    注:URI只代表资源的实体,严格地说,有些网址最后的.html后缀名是不必要的,因为这个后缀名表示格式,属于”表现层”范畴,而URI应该只代表”资源”的位置。

  • Representational 表象

    资源可以有各种具体的表现形式,比如文本可以有xml格式,html格式,json格式,甚至是二进制格式,图片可以有PNG格式,JPEG格式等。资源的一个具体表现形式,应该在HTTP请求的头信息中用AcceptContent-Type字段指定,这两个字段才是对”表现层”的描述。

  • State Transfer 状态转移

    通过http动词来实现资源的状态转移,用GET来请求资源,用POST来新建资源,用PUT来更新资源,用DELETE来删除资源。

下面对比下传统URL请求和RESTful风格请求的区别:

描述 传统请求 方法 RESTful请求 方法
查询 /user/query?name=mrbird GET /user?name=mrbird GET
详情 /user/getInfo?id=1 GET /user/1 GET
创建 /user/create?name=mrbird POST /user POST
修改 /user/update?name=mrbird&id=1 POST /user/1 PUT
删除 /user/delete?id=1 GET /user/1 DELETE

从上面这张表,我们大致可以总结下传统请求和RESTful请求的几个区别:

  1. 传统请求通过URL来描述行为,如create,delete等;RESTful请求通过URL来描述资源。
  2. RESTful请求通过HTTP请求的方法来描述行为,比如DELETE,POST,PUT等,并且使用HTTP状态码来表示不同的结果。
  3. RESTful请求通过JSON来交换数据。

RESTful只是一种风格,并不是一种强制性的标准。

Spring Boot中包含了一些注解,对应于HTTP协议中的方法:

  • @GetMapping对应HTTP中的GET方法;
  • @PostMapping对应HTTP中的POST方法;
  • @PutMapping对应HTTP中的PUT方法;
  • @DeleteMapping对应HTTP中的DELETE方法;
  • @PatchMapping对应HTTP中的PATCH方法。

具体规范

格式规范

根据RFC3986定义,URL是大小写敏感的。所以为了避免歧义,尽量使用小写字母。

RESTful API 应具备良好的可读性,当url中某一个片段(segment)由多个单词组成时,建议使用 - 来隔断单词,而不是使用 _。这主要是因为,浏览器中超链接显示的默认效果是文字并附带下划线,如果API以_隔断单词,二者会重叠,影响可读性。

/api/featured-post/     # GOOD
/api/featured_post/     # WRONG

协议

提供给用户的API,总是使用HTTPs协议。使用HTTPs协议还是HTTP协议本身和RESTful API并无关系,但是这对于提高网站的安全性很重要。

域名

API应该放在专有域名下,比如https://api.example.com/v1。也可以简单地把版本放在URL中,比如https://www.example.com/api/v1

版本

API的版本号应该放在URL中:

https://api.example.com/v1/

名词应该使用复数

所用的名词往往和数据库的表名对应,而数据库的表是一组记录的集合,因此URL中的名词即表示一组资源的集合,故URI中的名词要使用复数

https://api.example.com/v1/students
https://api.example.com/v1/schools
https://api.example.com/v1/employees

URL中不能使用动词

URI代表着一个资源,是一个实体,应该是名词,而不要把具体的动作放在URL中,对资源的操作应该通过HTTP的动词来实现。

不符合CRUD的情况

如果实在无法表示,也可使用动词,例如search没有对应的HTTP方法,可以在路径中使用search,更加直观

http://api.xxx.com/apiv3/search?timestamp=123213218&user_id=4192121&keyword=2134789

再例如创建了博客网站,如果想要发布一个博客,可以使用POST /articles/{:id}/publish

用HTTP动词表示对资源的操作

使用HTTP协议里的动词来实现资源的获取、删除、添加等操作

  • GET:从服务器获取资源
  • POST:在服务器新建一个资源
  • PUT:在服务器更新资源(客户端提供改变后的完整资源)
  • PATCH:在服务器更新资源(客户端提供改变的属性)
  • DELETE:从服务器中删除资源
GET     https://api.example.com/v1/schools                  # 列出所有学校
POST    https://api.example.com/v1/schools                  # 新建一个学校
GET     https://api.example.com/v1/schools/ID               # 列出指定学校的信息
DELETE  https://api.example.com/v1/schools/ID               # 删除指定学校

GET     https://api.example.com/v1/schools/ID/students      # 列出指定学校的所有学生
DELETE  https://api.example.com/v1/schools/ID/students/ID   # 删除指定学校的指定学生

HTTP状态码

  • 200 OK - [GET]:服务器成功返回用户请求的数据
  • 201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功
  • 204 NO CONTENT - [DELETE]:用户删除数据成功
  • 400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作
  • 401 UNAUTHORIZED:表示用户没有权限(令牌、用户名、密码错误)
  • 404 NOT FOUND:用户发出的请求针对的是不存在的记录,服务器没有进行操作
  • 500 INTERNAL SERVER ERROR:服务器发生错误,用户将无法判断发出的请求是否成功

其它

API的身份认证应该使用OAuth 2.0框架

服务器返回的数据格式,应该尽量使用JSON,避免使用XML。

JSON有可读性强,结构紧凑,支持的语言种类多的特点,因此JSON是RESTful API最常用的返回格式。


文章作者: 小小千千
版权声明: 本博客所有文章除特別声明外,均采用 CC BY 4.0 许可协议。转载请注明来源 小小千千 !
评论
  目录