Rest Framework

一、什么是Restful？
Restful，是一种软件架构风格，REST是Representational State Transfer的简称，我们称为“表征状态转移”，也叫“具象状态转换”。
我们对资源的操作，本质上是对资源的“增删改查”。

    (1)每一个URI代表一种资源；

　　（2）客户端和服务器之间，传递这种资源的某种表现层；

　　（3）客户端通过四个HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"。

---

REST设计的优点：
1、前后端分离
2、无状态
3、缓存
4、统一接口
5、支持按需代码

REST是面向资源进行的，而资源是通过URI进行暴露的。
URI 的设计只要负责把资源通过合理方式暴露出来就可以了。对资源的操作与它无关，操作是通过 HTTP动词来体现，所以REST 通过 URI 暴露资源时，会强调不要在 URI 中出现动词。

举例：左边是错误的，右边是正确的

GET /rest/api/getDogs --> GET /rest/api/dogs 获取所有小狗 
GET /rest/api/addDogs --> POST /rest/api/dogs 添加一个小狗 
GET /rest/api/editDogs/:dog_id --> PUT /rest/api/dogs/:dog_id 修改一个小狗
GET /rest/api/deleteDogs/:dog_id --> DELETE /rest/api/dogs/:dog_id 删除一个小狗

---

二、Restful API设计

1、域名：

将 api 部署在专用域名下：
http://api.example.com
或者将 api 放在主域名下：
http://www.example.com/api/

2、版本：

将 API 的版本号放在 url 中。
http://www.example.com/app/1.0/info
http://www.example.com/app/1.2/info

3、路径：

路径表示 API 的具体网址。每个网址代表一种资源。 资源作为网址，网址中不能有动词只能有
名词，一般名词要与数据库的表名对应。而且名词要使用复数。
错误示例：
http://www.example.com/getGoods
http://www.example.com/listOrders
正确示例：
获取单个商品
http://www.example.com/app/goods/1
获取所有商品
http://www.example.com/app/goods

4、使用标准的 HTTP 方法：

对于资源的具体操作类型，由 HTTP 动词表示。 常用的 HTTP 动词有四个。
GET SELECT ：从服务器获取资源。
POST CREATE ：在服务器新建资源。
PUT UPDATE ：在服务器更新资源。
DELETE DELETE ：从服务器删除资源。
示例：
获取指定商品的信息
GET http://www.example.com/goods/ID
新建商品的信息
POST http://www.example.com/goods
更新指定商品的信息
PUT http://www.example.com/goods/ID
删除指定商品的信息
DELETE http://www.example.com/goods/ID

5、过滤信息：

如果资源数据较多，服务器不能将所有数据一次全部返回给客户端。API 应该提供参数，过滤返
回结果。 实例：
指定返回数据的数量
http://www.example.com/goods?limit=10
指定返回数据的开始位置
http://www.example.com/goods?offset=10
指定第几页，以及每页数据的数量
http://www.example.com/goods?page=2&per_page=20

6、状态码：

服务器向用户返回的状态码和提示信息，常用的有：
200 OK ：服务器成功返回用户请求的数据
201 CREATED ：用户新建或修改数据成功。
202 Accepted：表示请求已进入后台排队。
400 INVALID REQUEST ：用户发出的请求有错误。
401 Unauthorized ：用户没有权限。
403 Forbidden ：访问被禁止。
404 NOT FOUND ：请求针对的是不存在的记录。
406 Not Acceptable ：用户请求的的格式不正确。
500 INTERNAL SERVER ERROR ：服务器发生错误。

7、错误信息：

一般来说，服务器返回的错误信息，以键值对的形式返回。
{
 error: 'Invalid API KEY'
}

8、响应结果：

针对不同结果，服务器向客户端返回的结果应符合以下规范。
返回商品列表
GET http://www.example.com/goods
返回单个商品
GET http://www.example.com/goods/cup
返回新生成的商品
POST http://www.example.com/goods
返回一个空文档
DELETE http://www.example.com/goods

9、使用链接关联相关的资源：

在返回响应结果时提供链接其他 API 的方法，使客户端很方便的获取相关联的信息。

10、其他：

服务器返回的数据格式，应该尽量使用 JSON，避免使用 XML。