restful专栏 01.drf基础概念

01.drf基础概念

[toc]{type: “ol”, level: [2, 3, 4, 5]}

概念

Django Rest FrameWork
rest:
    一个面向资源的架构
    互联网一切皆资源
restful:
    一种面向资源的架构风格
RestfulAPI:
    面向资源的应用接口

开发结构

数据库
Web后端/服务器
前端：
    PC网站
    移动端网站
    App
    小程序
前后端通过API文档来进行数据交互

API文档开发规范

1.协议：

http https 安全

2.域名：

尽量将API部署在一个专用的域名下
一个用于部署服务器的专用电脑
命名方式：
    https://api.example.com/
    https://example.com.api/

3.版本：

将版本号放在url中
https://example.com.api/v1/

4.路径：

每个网址代表一种资源，因此不能含有动词，且与数据库的表格对应，多使用复数
https://api.example.com/v1/zoos
https://api.example.com/v1/animals

5.HTTP动词

对于具体的操作类型，使用HTTP动词表示
常用的动词：
    GET：   从服务器获取一项或多项资源
    POST：  在服务器新建一项资源
    PUT:    在服务器更新资源[客户端提供改变后的完整资源 提供所有字段]
    PATCH:  在服务器更新资源[客户端提供改变的属性 提供修改字段]
    DELETE: 从服务器删除资源
不常用动词：
    HEAD：   获取资源的元数据
    OPTIONS：获取资源可以进行的操作：GET/POST...

删除动物园中的某个动物：DELETE /zoos/id/animals/id
https://api.library.com/v1/books/   GET获取全部、 POST增加
https://api.library.com/v1/books/id GET获取单个、 PUT/PATCH修改、 DELETE删除

6.过滤信息

?limit=n 指定返回记录的数量
?offset 指定返回记录的开始位置
?page=n&per_page=m 指定页码数以及每页的记录数
?sortby=name&order=asc 指定按某属性排序以及排序方式[asc/desc]
?animal_type_id 指定筛选条件

7.状态码

* 200 OK -[GET]                               服务器成功返回用户请求的数据
* 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]                   无法获取用户请求的数据格式
  410 Gone -[GET]                             用户请求的资源被永久删除，无法再次获取
  422 Unprocessable entity -[POST/PUT/PATCH]  当创建一个对象时，发生一个验证错误
* 500 INTERNAL SERVER ERROR -[*]              服务器发生错误，用户将无法判断发出的请求是否成功

8.错误处理

{
    error:"message"
}

9.返回结果

GET /collection：            返回资源对象的列表[数组]
GET /collection/resource：   返回单个资源对象
POST /collection：           返回新生成的资源对象
PUT /collection/resource：   返回完整的资源对象
PATCH /collection/resource： 返回完整的资源对象
DELETE /collection/resource：返回一个空文档[可添加状态吗及message]

10.超链接API

    {"fruit":
        {
            "pear": "https://www.example.api/fruits/pears"
            "banana": "https://www.example.api/fruits/bananas"
            "apple": "https://www.example.api/fruits/apples"
        }
    }