Restful入门

Restful入门

含义

1. REpresentational State Transfer的简写 ：表现层状态转移
2. 理解：URL定位资源，用HTTP动词（GET,POST,DELETE,DETC）描述操作。

为什么要用？

1. 方便不同的前端设备与后端进行通信

版本

版本号拼接在 URL
api.xxx.com/v1/users
另一种做法是，将版本号放在HTTP头信息中。
版本号只允许枚举，不允许判断区间。

请求

一般来说 API 的外在形式无非就是增删改查（当然具体的业务逻辑肯定要复杂得多），而查询又分为详情和列表两种，在 RESTful 中这就相当于通用的模板。例如针对文章（Article）设计 API，那么最基础的 URL 就是这几种：

路径

HTTP动词

GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。

示例

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

返回值的约束

GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档

常见问题

1. 幂等：调用多次没影响
2. 特点：面向资源

参考资料

• RESTful API 设计指南
• KONG　Restful