经常搞不清楚我们常说的HTTP API和Restful API是什么关系,HTTP API是Restful API的实现和表现,Restful API是HTTP API的基础,提供了标准接口和规范。

基本概念

REST – REpresentational State Transfer 直接翻译:表现层状态转移。REST只是一组关于如何使用HTTP的规则规范,或者是一种设计风格,但并不是一个标准,只是提倡我们使用,所以业内认为REST是我们都应该使用HTTP的方式。

Resource:资源,即数据。
Representational:某种表现形式,比如用JSON,XML,JPEG等;
State Transfer:状态变化。通过HTTP动词实现。

rest基本规范

遵循rest规则的http api就是restful api,那么rest规则有哪些?

资源路径

对于rest资源的定义,即URL的定义,是最重要的,想要设计出优雅的、易读的rest 接口,其实还是听不容易的。

1、URL中不能有动词

在Restful架构中,每个网址代表的是一种资源,所以网址中不能有动词,只能有名词,动词由HTTP的 get、post、put、delete 四种方法来表示。

2、URL结尾不应该包含斜杠“/”

这是作为URL路径中处理中最重要的规则之一,正斜杠(/)不会增加语义值,且可能导致混淆。REST API不允许一个尾部的斜杠,不应该将它们包含在提供给客户端的链接的结尾处。

许多Web组件和框架将平等对待以下两个URL:

http://api.canvas.com/shapes/
http://api.canvas.com/shapes

但是,实际上URL中的每个字符都会计入资源的唯一身份的识别中。

两个不同的URL映射到两个不同的资源。如果URL不同,那么资源也是如此,反之亦然。因此,REST API必须生成和传递精确的URL,不能容忍任何的客户端尝试不精确的资源定位。

有些API碰到这种情况,可能设计为让客户端重定向到相应没有尾斜杠的URL(也有可能会返回301 - 用来资源重定向)。

3、正斜杠分隔符”/“必须用来指示层级关系

url的路径中的正斜杠“/“字符用于指示资源之间的层次关系。

例如:

http://api.user.com/schools/grades/classes/boys - 学校中所有的男生

http://api.college.com/students/3248234/courses - 检索id为3248234的学生学习的所有课程的清单。

4、应该使用连字符”-“来提高URL的可读性,而不是使用下划线”_”

为了使URL容易让人们理解,请使用连字符”-“字符来提高长路径中名称的可读性。

一些文本查看器为了区分强调URL,常常会在URI下加上下划线。这样下划线”_”字符可能被文本查看器中默认的下划线部分地遮蔽或完全隐藏。

为避免这种混淆,请使用连字符”-“而不是下划线

5、URL路径中首选小写字母

RFC 3986将URI定义为区分大小写,但scheme 和 host components除外。

6、URL路径名词均为复数

为了保证url格式的一致性,建议使用复数形式。

状态变化

对于rest api资源的操作,由HTTP动词表示,但是很多动词可以多种使用方式,rest明确定义http的什么动作操作什么资源,避免滥用。

1、CURD操作

GET: 获取资源
POST: 新建资源
PUT:在服务器更新资源(向客户端提供改变后的所有资源)
PATCH: 在服务器更新资源(向客户端提供改变的属性)
DELETE:删除资源
PATCH一般不用,用PUT

2、资源过滤

在获取资源的时候,有可能需要获取某些“过滤”后的资源,例如指定前10行数据

http://api.user.com/schools/grades/classes/boys?page=1&page-size=10

3、返回状态码推荐标准HTTP状态码

有很多服务器将返回状态码一直设为200,然后在返回body里面自定义一些状态码来表示服务器返回结果的状态码。由于rest api是直接使用的HTTP协议,所以它的状态码也要尽量使用HTTP协议的状态码。

200 OK 服务器返回用户请求的数据,该操作是幂等的
201 CREATED 新建或者修改数据成功
204 NOT CONTENT 删除数据成功
400 BAD REQUEST 用户发出的请求有问题,该操作是幂等的
401 Unauthoried 表示用户没有认证,无法进行操作
403 Forbidden 用户访问是被禁止的
404 不存在
422 Unprocesable Entity 当创建一个对象时,发生一个验证错误
500 INTERNAL SERVER ERROR 服务器内部错误,用户将无法判断发出的请求是否成功
503 Service Unavailable 服务不可用状态,多半是因为服务器问题,例如CPU占用率大,等等

4、规范

GET /collections 返回资源列表
GET /collections/:id 返回单独的资源
POST /collections 返回新生成的资源对象
PUT /collections/:id 返回完整的资源对象
PATCH /collections/:id 返回被修改的属性
DELETE /collections/:id 返回一个空文档

我们提供restful类型的api有什么好处呢?因为rest有限制,可以是一个统一的规范。就具有通用性。下面是比较官方rest的主要规则,根据全面,但是比较难懂

1. 使用客户/服务器模型。客户和服务器之间通过一个统一的接口来互相通讯。
2. 层次化的系统。在一个REST系统中,客户端并不会固定地与一个服务器打交道。
3. 无状态。在一个REST系统中,服务端并不会保存有关客户的任何状态。也就是说,客户端自身负责用户状态的维持,并在每次发送请求时都需要提供足够的信息。
4. 可缓存。REST系统需要能够恰当地缓存请求,以尽量减少服务端和客户端之间的信息传输,以提高性能。
5. 统一的接口。一个REST系统需要使用一个统一的接口来完成子系统之间以及服务与用户之间的交互。这使得REST系统中的各个子系统可以独自完成演化。
5. 唯一资源标识来标识资源
6. 传递消息的自身描述
7. 返回资源的自身描述
8. 可选的超媒体即应用状态引擎(HATEOAS) 

rest不但是上面基本的规范,也是一种代码架构设计思想,主要用于webserver,把Web 系统的服务抽象为资源,设计对应规范的api,进行crud操作,很多mvc就是使用了这种思想。

restful API和http api