一、什么是RESTful

历史

Roy Thomas Fielding （菲尔丁）是HTTP 协议的主要作者之一。它在2000年于加州大学艾尔文分校所做的博士毕业论文Architectural Styles and the Design of Network-based Software Architectures 中，描述了一种称为REST 的网络软件架构风格，目的是方便不同软件在网络中互相传递消息。

注意，REST 不是凭空创建出来的所谓「标准」，而只是基于现有HTTP 协议而提出的一种「简单和易于理解的架构风格」，如果大家都能使用这种风格则无疑会方便互联网中的HTTP 信息交互。

释义

REST - Representational State Transfer 意为「具象状态转移」, REST 并不好理解，不过当我们理解了网络信息交换的主体是「资源(Resource)」时，我们其实可以明白REST 说的是「资源的状态转移」。

ful 是形容词后缀表示「有…性质的」，可知RESTful 指：有具象状态转移性质的……。在Web 应用开发时，当我们设计了一个有具象状态转移性质的Web API 时，我们称之为RESTful API。

二、RESTful API 规则推荐

虽然REST 有6个指导性约束，但它不是协议更没有「官方标准」，所以参考了网络上若干解释后我约定如下规则：

协议与域名

协议使用HTTPS，域名使用专用于API 的域名，例如：

https://api.ddupa.com
版本

虽然Roy Thomas Fielding 认为设计良好的API 不应该有版本这个概念，因为这增加了客户端的理解难度，还会有潜在的服务升级后客户端不可用的风险。但基于业界通用做法，我们还是会使用版本，位置在域名之后，例如：

https://api.ddupa.com/v1
使用名词且用复数

在RESTful 风格中，每个URL 代表一种资源（resource），亦即网址是对资源的静态描述，固只能用名词而禁用动词。另外，资源通常都是数据的「集合」，所以API 中的名词也应使用复数。

举例来说，假设api.ddupa.com 的学校（school）模块提供了管理员可管理信息的接口，包括学生和课程，则它应被设计成如下格式：

https://api.ddupa.com/v1/school/students

https://api.ddupa.com/v1/school/courses
HTTP 的动词

目前为止我们只定义了静态的资源，接下来我们为了使其发生「状态转移」必须使用HTTP 的动词来达成目的。

HTTP 动词有很多，我们约定使用如下几种即能满足我们的需求：

GET : 从服务器获取资源（一个或多个）。

POST : 在服务器新建一个资源。

PUT : 更新服务器的资源（客户端提供的所有属性将被使用，例如{name:null}将使服务器将name属性值设置为null）。

PATCH : 更新服务器的资源（客户端仅提供改变的属性即可，null属性将被忽略，例如{name:null}将被服务器忽略）。

DELETE : 从服务器删除资源。

举例如下：

GET /courses/{id} : 获取id代表的课程。

GET /courses/pages : 获取课程的某一页（一页包含多个课程）。

POST /courses : 新建一个课程。

PUT /courses/{id} : 更新id代表的课程的全部信息。

PATCH /courses/{id} : 更新id代表的课程的部分信息。

DELETE /courses/{id} : 删除课程。
GET 的信息过滤

获取资源时通常我们只对有某些特征的资源感兴趣，所以API 应该提供参数，用以过滤结果。

例如：

?limit=10 : 指定返回资源数量。

?offset=10 : 指定返回资源开始位置。

?pageNo=3&pageSize=20 : 指定页码和每页记录数。

?sortby=createTime&order=desc : 指定排序规则和顺序。

?type=1 : 指定返回type为1的资源。
Request 数据格式约定
- 路径参数
  
  所有HTTP 方法均可用，在URL 路径参数部分中，例如/{id}。
- 查询参数
  
  GET 方法可用，在URL 中查询参数部分，例如?type=1。
- 请求体
  
  POST/PUT/PATCH 方法可用，在Request Body 部分，且必须是Content-Type : application/json;charset=UTF-8。
Response 约定

HTTP 状态码如：200, 404, 500等当然应该被使用，除此之外我们还应该定义一个统一的响应格式，内容类型为Content-Type : application/json;charset=UTF-8，例如：
```
{
  "state": 1,
  "message": "操作成功/操作失败",
  "content": {
    "data": {}
  }
}
```

三、参考

规则

实例

设计一个RESTful 规则

一、什么是RESTful

二、RESTful API 规则推荐

三、参考

猜你喜欢