RESTful API浅谈

小程序：扫一扫查出行
【扫一扫了解最新限行尾号】
复制小程序

一、REST的由来

全称：REST，全称是Resource Representational State Transfer，即： 资源在网络中以某种形式进行状态转移 。————所谓状态的转移，可参考《HTTP权威指南》一书中对协议的详细解释，此处不过多赘述！

出现：REST最早是由Roy Fielding博士发表的论文中提到的，他也曾参与设计了HTTP协议。论文地址：http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

定义：简单来说REST是一种系统架构设计风格（而非标准），一种分布式系统的应用层解决方案。

背景：早期的网页端是前后台一起的，比如PHP、JSP等。而随着近几年移动端的快速发展和分布式架构的应用，各种Client层出不穷，这个时候就需要有个统一的机制，来为前后端通信提供服务。

而RESTful API就是目前比较成熟的的一套应用程序API设计理论。

目的：Client和Server端进一步解耦。

应用：最为经典的莫过于github API。

二、RESTful的特征和优点

1、 客户端-服务器（Client-Server） ：提供服务的服务器和使用服务的客户端分离解耦；

优点：提高客户端的便捷性（操作简单）

简化服务器提高可伸缩性（高性能、低成本）

允许客户端服务端分组优化，彼此不受影响

2、无状态（Stateless） ：来自客户的每一个请求必须包含服务器处理该请求所需的所有信息（请求信息唯一性）；

优点：提高可见性（可以单独考虑每个请求）

提高可靠性（更容易故障恢复）

提高了可扩展性（降低了服务器资源使用）

3、可缓存（Cachable） ：服务器必须让客户端知道请求是否可以被缓存？如果可以，客户端可以重用之前的请求信息发送请求；

优点：减少交互连接数

减少连接过程的网络时延

4、分层系统（Layered System） ：允许服务器和客户端之间的中间层（代理，网关等）代替服务器对客户端的请求进行回应，而客户端不需要关心与它交互的组件之外的事情；

优点：提高了系统的可扩展性

简化了系统的复杂性

5、统一接口（Uniform Interface） ：客户和服务器之间通信的方法必须是统一化的。（例如：GET,POST,PUT.DELETE）

优点：提高交互的可见性

鼓励单独优化改善组件

6、支持按需代码（Code-On-Demand，可选） ：服务器可以提供一些代码或者脚本并在客户的运行环境中执行。

优点：提高可扩展性

三、概要设计方法

1、协议

API与Client的通信协议，总是使用HTTPS协议。

PS：使用HTTPS协议和RESTful API本身没有多大关系，但是对于增加网站的安全是非常重要的，特别是如果提供的是公开的API，那么HTTPS久更显得重要了。

2、域名

应该尽量将API部署在专用的域名下面，比如：

https://api.github.com

如果API变化较大，可以把API设计为子域名，比如：

https://example.com/api/v1

3、版本（Versioning）

一般而言应该将API放入URL中，比如：

https://example.com/api/v1

还可以将版本号放入HTTP信息头中，但这样不如放入URL方便和直观。

4、路径（Endpoint）

在协议中，每个网址代表一种资源的存放地址，所以网址终不能有动词，只能有名词，而且名词一般都应该与数据库的表字段对应，且API中的名词应该使用复数。例如：

/users/:username/repos

/users/:org/repos

/repos/:owner/:repo

/repos/:owner/:repo/tags

/repos/:owner/:repo/branches/:branch

PS：根据RFC3986定义，URL是大小写敏感的，所以应该尽量使用小写字母来命名！

5、方法（Method）

有了资源的URL设计，所有针对资源的操作都是使用HTTP方法指定的，常见的方法有（括号中为对应的SQL命令）：

Verd	描述
HEAD（SELECT）	只获取某个资源的头部信息
GET（SELECT）	获取资源
POST（CREATE）	创建资源
PATCH（UPDATE）	更新资源的部分属性（很少用，一般用POST代替）
PUT（UPDATE）	更新资源，客户端需要提供新建资源的所有属性
DELETE（DELETE）	删除资源

比如：

GET /user:列出所有的用户POST /user:新建一个用户PATCH /user/ID:更新某个指定用户的信息DELETE /user/ID:删除所有用户

6、数据过滤（Filtering）

如果数据量太大，服务器不可能将所有数据返回给用户。API应该提供参数（比如Query），过滤返回结果。比如：

?limit=10：指定返回记录的数量

?offset=10：指定返回记录的开始位置

?page=2&per_page=100：指定第几页，以及每页的记录数

?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序

?state=close：指定筛选条件

7、状态码

在HTTP报文构成中，有个字段很重要：status code。它说明请求的大致情况，是否正常处理、出现了什么错误等。状态码都是三位数，大概分为了一下几个区间：

状态码	描述
2XX	请求正常处理并返回
3XX	重定向，请求的资源位置发生变化
4XX	客户端发送的请求有误
5XX	服务器端的错误