RESTful接口

什么是RESTful接口

Restful是英文Representational State Transfer(表象性状态转变)或者表述性状态转移；Rest是web服务的一种架构风格，使用HTTP、URL、XML、JSON、HTML等广泛流行的标准和协议； 轻量级，跨平台，跨语言的架构设计，是一种设计风格，不是一种标准，是一种思想

RESTful主要思想

• 每一个URI（统一资源标志符）代表一种资源
• 客户端使用GET、POST、PUT、DELETE4个表示操作方式的动词对服务端资源进行操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源；
• 通过操作资源的表现形式（XML或HTML）来操作资源
• 客户端与服务端之间的交互在请求之间是无状态的，从客户端到服务端的每个请求都必须包含理解请求所必需的信息。

HTTP 方法

请求方法	描述
GET	从服务器查询，可以在服务器通过请求的参数区分查询的方式。
POST	在服务器新建一个资源，调用insert操作。
PUT	在服务器更新资源（客户端提供改变后的完整资源）（修改全部数据）
PATCH	在服务器更新资源（客户端提供改变的属性）（修改部分数据）
DELETE	从服务器删除资源。
HEAD	获取资源的元数据。
OPTIONS	获取信息，关于资源的哪些属性是客户端可以改变的。

例子：
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：删除某个指定动物园的指定动物

过滤信息

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

下面是一些常见的参数。

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

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。 比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

状态码

每条 HTTP 响应报文返回时都会携带一个状态码。状态码是一个三位数字的代码，告知客户端请求是否成功， 或者是否需要采取其他动作。

状态码分成如下几个系列：

状态码	定义	说明
1XX	请求被接受	一般只在实验环境下使用
2XX	成功	操作成功的收到，理解和接收
3XX	重定向	为了完成请求，进行进一步措施
4XX	客户端错误	请求的语法有错误或者不能完全被满足
5XX	服务器错误	服务器无法完成明显有效的请求

常见的状态码

HTTP状态码	含义	描述
200	OK - [GET]	服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201	CREATED - [POST/PUT/PATCH]	用户新建或修改数据成功。
202	Accepted - [*]	表示一个请求已经进入后台排队（异步任务）
204	NO CONTENT - [DELETE]	用户删除数据成功。
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 - [*]	服务器发生错误，用户将无法判断发出的请求是否成功。