Django REST framework

1.Restful 设计风格

1.1 Restful 概念

REST这个词，是 Roy Thomas Fielding 在他2000年的博士论文中提出的。

Fielding将他对互联网软件的架构原则，定名为REST，即Representational State Transfer的缩写，可以根据单词含义翻译为“表现层状态转化”。

如果一个架构符合REST原则，就称它为 RESTful 架构。

例如对于后端数据库中保存了商品的信息，前端可能需要对商品数据进行增删改查，那相应的每个操作后端都需要提供一个API接口，如下表格所示：

请求方法	请求地址	后端操作
GET	/goods	获取所有商品
POST	/goods	增加商品
GET	/goods/1	获取编号为1的商品
PUT	/goods/1	修改编号为1的商品
DELETE	/goods/1	删除编号为1的商品

Restful 设计架构有以下特点：

1. 每一个URL代表一种资源。
2. 客户端和服务器之间，传递这种资源的某种表现层。
3. 客户端和服务器之间，通过 HTTP 动词，对服务器端的资源进行获取、修改、删除等操作，实现“表现层状态转化”。

1.2 Restful 设计方法

1. 协议

   API与用户的通信协议，总是使用 HTTPS 协议。

2. 域名

   应该尽量将 API 部署在专用域名之下。

   https://api.example.com

   如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。

   https://example.org/api/

3. 版本

   应该将API的版本号放入 URL。

   https://api.example.com/v1/

4. 路径（Endpoint）

   路径又称“终点”（endpoint），表示 API 的具体网址。

   在 Restful 架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。

   举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

   https://api.example.com/v1/zoos
   https://api.example.com/v1/animals
   https://api.example.com/v1/employees

5. HTTP 动词

   对于资源的具体操作类型，由HTTP动词表示。

   常用的HTTP动词有下面五个（括号里是对应的SQL命令）。

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

   还有两个不常用的HTTP动词。

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

6. 过滤信息（Filtering）

   如果记录数量很多，服务器不可能都将它们返回给用户。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 的含义是相同的。

7. 状态码（Status Code）

   服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

8. 错误处理（Error handing）

   如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。

   {
       error: "Invalid API key"
   }

9. 返回结果

   针对不同操作，服务器向用户返回的结果应该符合以下规范。

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

10. Hypermedia API

    RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。

    比如，当用户向api.example.com的根目录发出请求，会得到这样一个文档。

    {"link": {
      "rel":   "collection https://www.example.com/zoos",
      "href":  "https://api.example.com/zoos",
      "title": "List of zoos",
      "type":  "application/vnd.yourformat+json"
    }}

    上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址），href表示API的路径，title表示API的标题，type表示返回类型。

    Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计，访问api.github.com会得到一个所有可用API的网址列表。

    {
      "current_user_url": "https://api.github.com/user",
      "authorizations_url": "https://api.github.com/authorizations",
      // ...
    }

    从上面可以看到，如果想获取当前用户的信息，应该去访问api.github.com/user，然后就得到了下面结果。

    {
      "message": "Requires authentication",
      "documentation_url": "https://developer.github.com/v3"
    }

    上面代码表示，服务器给出了提示信息，以及文档的网址。

11. 其他

    (1) API的身份认证应该使用OAuth 2.0框架。

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

2.Django Rest Framework

2.1 Django Rest Framework框架

1. 序列化和反序列化提示

   在开发 REST API 的视图中，虽然每个视图具体操作的数据不同，但增、删、改、查的实现流程基本相同。

   • 增：校验请求数据 -> 执行反序列化过程 -> 保存数据库 -> 将保存的对象序列化并返回
   • 删：判断要删除的数据是否存在 -> 执行数据库删除
   • 改：判断要修改的数据是否存在 -> 校验请求的数据 -> 执行反序列化过程 -> 保存数据库 -> 将数据序列化并返回。
   • 查：查询数据库 -> 将数据序列化并返回

   DRF将序列化和反序列化的业务逻辑进行了封装，只需要将序列化和反序列化的数据传递给DRF即可。

2. DRF作用

   Django Rest Framework可以帮助我们简化序列化和反序列化部分的代码编写，大大提高 REST API 的开发效率。

3. 相关文档

   • 官方文档：https://www.django-rest-framework.org/
   • 源码：https://github.com/encode/django-rest-framework/tree/master

2.2 安装

使用 pip 安装 djangorestframework 第三方包，命令如下：

pip install djangorestframework

Django 项目 settings.py 配置文件中的 INSTALLED_APPS 配置，添加 djangorestframework ，如下所示：

INSTALLED_APPS = [
    ...
    'rest_framework'
]

如果想要使用页面浏览 api 以及 REST Framework 的登录注销视图，添加如下内容在 Django 项目的的根路由文件：

urlpatterns = [
    ...
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

2.3 DRF实现增删改查接口流程

1. 序列化（Serializers）

   在 APP 下编写 serializers.py 文件，编写如下内容：

   from django.contrib.auth.models import Group, User
   from quickstart.models import Books
   from rest_framework import serializers
   
   
   class UserSerializer(serializers.HyperlinkedModelSerializer):
       class Meta:
           model = User
           fields = ['url', 'username', 'email', 'groups']
   
   
   class GroupSerializer(serializers.HyperlinkedModelSerializer):
       class Meta:
           model = Group
           fields = ['url', 'name']
   
   class BookSerializer(serializers.HyperlinkedModelSerializer):
       class Meta:
           model = Books
           fields = ['url', 'title', 'author', 'desc']

2. 视图函数

   这里比较特殊，需要将引用 DRF 提供的 viewsets.ModelViewSet 基础类以及编写对应的类对象，例如需要写 Books 的 Restful 接口，则编写一个基于 viewsets.ModelViewSet 的 BookViewSet。

   from django.contrib.auth.models import Group, User
   from quickstart.models import Books
   from rest_framework import permissions, viewsets
   
   from quickstart.serializers import GroupSerializer, UserSerializer, BookSerializer
   
   # from .serializers import GroupSerializer, UserSerializer
   
   class UserViewSet(viewsets.ModelViewSet):
       """
       API endpoint that allows users to be viewed or edited.
       """
       queryset = User.objects.all().order_by('-date_joined')
       serializer_class = UserSerializer
       permission_classes = [permissions.IsAuthenticated]
   
   
   class GroupViewSet(viewsets.ModelViewSet):
       """
       API endpoint that allows groups to be viewed or edited.
       """
       queryset = Group.objects.all().order_by('name')
       serializer_class = GroupSerializer
       permission_classes = [permissions.IsAuthenticated]
   
   class BookViewSet(viewsets.ModelViewSet):
       """
       API endpoint that allows groups to be viewed or edited.
       """
       queryset = Books.objects.all().order_by('title')
       serializer_class = BookSerializer
       # permission_classes = [permissions.IsAuthenticated]

3. 路由函数

   路由函数这里也需要引用 DRF 提供的 routers 方法，编写路由。

   from rest_framework import routers
   from quickstart import views
   
   router = routers.DefaultRouter()
   router.register(r'users', views.UserViewSet)
   router.register(r'groups', views.GroupViewSet)
   router.register(r'books', views.BookViewSet)

4. 接口测试

   • 获取图书的列表（get，/books）

     

   • 获取指定的图书信息（get，books/id）

     

   • 修改图书信息（put，/books/id）

     

   • 获取信息，资源的那些属性是可以改变的（options，/books）

     

   • 删除图书（delete, /books/id）

     

     如上所示，通过 DRF 能够便捷的进行 Restful API 的开发，而不需要手动再去开发对应的方法，此外 DRF 也支持分页器和权限的管理，有需要可以继续了解。