23.7.1. Django-RESTful-API基础 ¶

1 RESTful规范-如何写API ¶

API接口应该如何写？API跟URL有什么不同？这绝对是不可以被忽略的问题，如果API写得乱七八糟，很有可能会失去负责前端开发的同事的信任。将API写得“高大上”，也是一名开发者工匠精神的一种体现。下面来介绍如何写API。

（1）如果是对同一个表进行数据操作（增、删、改、查），应该使用一条API，然后根据method的不同，进行不同的操作。

GET/POST/PUT/DELETE/PATCH

（2）面向资源编程，通过API提交的参数最好是名词，比如name，尽量少用动词。

http://www.abc.com/name

（3）体现版本，在API中加入像v1、v2这样的版本代号：

http://www.abc.com/v1/namehttp://www.abc.com/v2/name

（4）体现API，让使用者一眼能看出这是API而不是URL，应该在API中加入提示：

http://www.abc.com/api/v1/namehttp://www.abc.com/api/v2/name

（5）使用HTTPS，这一项原本是为了安全考虑，但是随着国内外互联网环境对安全性越来越重视，谷歌浏览器对所有不是HTTPS请求的链接全都会提示用户此链接为不安全链接，腾讯等平台也对小程序等产品强制要求使用HTTPS协议。不过，好在国内许多提供云服务的公司，像腾讯云、阿里云等，都提供免费的SSL证书，供开发者去申请。

https://www.abc.com/api/v1/namehttps://www.abc.com/api/v2/name

（6）响应式设置状态码，例如，200和201代表操作成功，403代表权限不够，404代表没有指定资源，500代表运行时发现代码逻辑错误等。

return HttpResponse('adgbag',status=300)

服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。

OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
NO CONTENT - [DELETE]：用户删除数据成功。
INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

（7）API的参数中加入筛选条件参数，也可以理解为获取资源优先选择GET的方式。

https://www.abc.com/api/v2/name?page=1&size=10

（8）返回值的规范，不同的method操作成功后，后端应该响应的返回值如下：

https://www.abc.com/api/v1/name

不同的提交方式代表对数据进行不同的操作：

GET：所有列表。
POST：新增的数据。

https://www.abc.com/api/v1/name/1

GET：单条数据。
PUT：更新，返回更新的数据。
PATCH：局部更新，返回更新的数据。
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： //删除某个指定动物园的指定动物

（9）返回错误信息，应该加入错误代号code，让用户能直接看出是哪种类型的错误。

ret {
    code:1000，
    data:{
        {'id':1,'title':'lala'}
    }
}

（10）返回的详细信息，应该以字典的形式放在data中。

ret {
    code:1000，
    data:{
        {'id':1,'title':'lala','detail':http://www.……}
    }
}

RESTful规范是业内约定俗成的规范，并不是技术上定义的公式，在实际生产使用中，大家还是要根据业务灵活运用。

RESTful架构和RESTful API设计总结

https://www.yuque.com/fcant/sys/qd2ay1

1.1 详细文献参考 ¶

RESTful 规范

https://www.cnblogs.com/welan/p/9875103.html

2 Django REST framework简介 ¶

如果可以将Django REST framework的10个常用组件融会贯通，那么使用Django开发前后端分离的项目中有可能遇到的绝大部分需求，都能得到高效的解决。

Django REST framework的10个常用组件如下：

权限组件；
认证组件；
访问频率限制组件；
序列化组件；
路由组件；
视图组件；
分页组件；
解析器组件；
渲染器组件；
版本组件。

Django REST framework官方文档的地址

https://www.django-rest-framework.org/

23.7.1. Django-RESTful-API基础¶

1 RESTful规范-如何写API¶

1.1 详细文献参考¶

2 Django REST framework简介¶

23.7.1. Django-RESTful-API基础 ¶

1 RESTful规范-如何写API ¶

1.1 详细文献参考 ¶

2 Django REST framework简介 ¶