RESTFUL API详解

前言

现在客户端-服务端模型发展越来越快,客户端支持的的设备也越来越多(平板,浏览器,电脑客户端,手机 app 端,微信端等等),为了方便前后端交互,制定统一的规则,多种 API 规范出现了,RESTFUL API 就是目前最流行的一种,我对 RESTFUL API 做了一些整理,如下

RESTFUL API简介

RESTFUL API(Representational State Transfer),翻译为表现层状态转换,表现层是 MVC 设计模式中的View,比如在 web 开发中就是网页,状态转化是一个很笼统的说法,既包含了通过不同的 HTTP 请求类型去获取数据,且包含了 HTTP 返回的状态码,和传统的 http 请求方式相比,行为更复杂状态更多,所以统称为状态转化

RESTFUL API 有几大基本特征

1
2
3
4
5
6
7
8
9
1.有版本号控制

2.通过HTTP请求类型(如POST,GET)和请求地址(URL)共同决定这个请求需要处理的业务

3.对于资源的命名全为名词

4.HTTP返回状态码更多,对应不同的服务状态

5.支持请求字段扩展,增加参数,用于条件过滤(这点我们太熟悉了)

域名部署选择

尽量将 RESTFUL API 用专属域名进行部署,如 https://api.example.com,如果你的应用规模没有那么大,也可以考虑使用 https://example.com/api 我个人更喜欢后者,接来的讲解也会以后者为基础进行讲解

版本号

紧跟着域名的是版本号,用来告诉用户该 RESTFUL API 的版本,格式如下 https://example.com/api/v1.0,表明当前版本号为 v1.0

资源路径

版本号后面的就是请求的资源名了,如 https://api.example.com/v1/zoos,其中 zoos 代表的是某一类业务资源,很可能是复数。命名一般会为某类业务名称或者数据库名,且为名词。

HTTP请求类型

常见的HTTP请求类型有如下五种(分别对应的是增删改查):

1
2
3
4
5
6
7
8
9
10
POST(CREATE):在服务器新建一个资源
DELETE(DELETE):从服务器删除资源
PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源,也就是全部修改)
PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性,部分修改)
GET(SELECT):从服务器取出资源(一项或多项)

下面两个不常见:

HEAD:获取资源的元数据,如请求头,长度,需改时间等,不返回body部分。
OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的,一般是和跨域有关的。

通常请求类型和资源路径一起用,同样的资源路径,不同的请求类型,对应不同的处理方式,如下:

1
2
3
4
5
6
7
8
GET /zoos:列出所有动物园
POST /zoos:新建一个动物园
GET /zoos/ID:获取某个指定动物园的信息
PUT /zoos/ID:更新某个指定动物园的信息(提供该动物园的全部信息)
PATCH /zoos/ID:更新某个指定动物园的信息(提供该动物园的部分信息)
DELETE /zoos/ID:删除某个动物园
GET /zoos/ID/animals:列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID:删除某个指定动物园的指定动物

返回状态码

状态码是服务端返回给客户端时候的http状态信息,可以告诉客户端之前那条请求目前是什么处理状态

状态码 类别 原因短语
1XX Informational(信息状态码) 接收的请求正在处理
2XX Success(成功状态码) 请求正常处理完毕
3XX Redireection(重定向状态码) 每次请求中使用重定向不要超过 5 次。
4XX Client Error(客户端错误状态码) 表示请求可能出错,服务器无法处理请求
5XX Server Error(服务器错误状态码) 服务器本身的错误,而不是请求出错

常见状态码如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
100 Continue 表明到目前为止都很正常,客户端可以继续发送请求或者忽略这个响应
200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
204 NO CONTENT - [DELETE]:用户删除数据成功。
301 Moved Permanently 永久性重定向
302 Found 临时性重定向
400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。
401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
504 Gateway Time-out http 请求服务器超时

过滤信息

过滤信息是我用的最多的,有时候一些查询非常的复杂,有许多参数需要传入,这个时候就需要用到过滤信息。传参的方法和以前用的 get,post 一样,格式如 ?参数名=值&参数名=值,加到 url 后面,作为 http 参数传递到服务端

样例如下:

1
2
3
4
5
?limit=10:指定返回记录的数量
?offset=10:指定返回记录的开始位置。
?page=2&per_page=100:指定第几页,以及每页的记录数。
?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
?animal_type_id=1:指定筛选条件

错误处理

当状态码不太正常的时候我们就应该在返回数据中包含错误信息,通用错误处理格式如下:

1
2
3
{
error: "Invalid API key"
}

补充

幂等性:指使用相同参数重复执行,能获得相同结果

http://www.ruanyifeng.com/blog/2014/05/restful_api.html

坚持原创技术分享,您的支持将鼓励我继续创作!