利用 Django REST framework 编写 RESTful API

利用 Django REST framework 编写 RESTful API

Updateat 2015/12/3: 增加 filter

最近在玩 Django,不得不说 rest_framework 真乃一大神器,可以轻易的甚至自动化的搞定很多事情,比如:

  • 自动生成符合 RESTful 规范的 API

    • 支持 OPTION、HEAD、POST、GET、PATCH、PUT、DELETE
    • 根据 Content-Type 来动态的返回数据类型(如 text、json)
  • 生成 browserable 的交互页面(自动为 API 生成非常友好的浏览器页面)
  • 非常细粒度的权限管理(可以细粒度到 field 级别)

示意图


安装

$ pip install djangorestframework
$ pip install markdown

概述

Django Rest framework 的流程大概是这样的

  1. 建立 Models
  2. 依靠 Serialiers 将数据库取出的数据 Parse 为 API 的数据(可用于返回给客户端,也可用于浏览器显示)
  3. ViewSet 是一个 views 的集合,根据客户端的请求(GET、POST等),返回 Serialiers 处理的数据
    • 权限 Premissions 也在这一步做处理
  4. ViewSet 可在 Routers 进行注册,注册后会显示在 Api Root 页上
  5. 在 urls 里注册 ViewSet 生成的 view,指定监听的 url

希望全面细致了解的人请移步去看官方文档,我这里就不一步步的细说了,而是分块来进行介绍


准备工作 & Models

让我们来写个小项目练练手

  1. 先用 manage.py startproject rest 来生成一个项目
  2. 再用 manage.py createsuperuser 创建用户(后面权限管理会用到)
  3. 初始化数据库 manage.py migrate

然后当然是编写 models,为了展示 rest_framework 的强大之处,我给 models 定义了一个自定义的 field

# myproject/myapp/models.py

#! /usr/bin/env python
# -*- coding: utf-8
from __future__ import unicode_literals, absolute_import
import cPickle as pickle

from django.db import models
from django.contrib.auth.models import User

class SerializedField(models.TextField):

    """序列化域
    用 pickle 来实现存储 Python 对象
    """
    __metaclass__ = models.SubfieldBase  # 必须指定该 metaclass 才能使用 to_python

    def validate(self, val):
        raise isinstance(val, basestring)

    def to_python(self, val):
        """从数据库中取出字符串,解析为 python 对象"""
        if val and isinstance(val, unicode):
            return pickle.loads(val.encode(‘utf-8‘))

        return val

    def get_prep_value(self, val):
        """将 python object 存入数据库"""
        return pickle.dumps(val)

class MyModel(models.Model):

    created_at = models.DateTimeField(auto_now_add=True)
    # 注意这里建立了一个外键
    owner = models.ForeignKey(User, related_name=‘mymodels‘)
    field = models.CharField(max_length=100)
    options = SerializedField(max_length=1000, default={})

Serializers

定义好了 Models,我们可以开始写 Serializers,这个相当于 Django 的 Form

# myproject/myapp/serializers.py

#! /usr/bin/env python
# -*- coding: utf-8
from __future__ import unicode_literals, absolute_import
import json

from django.contrib.auth.models import User
from rest_framework import serializers

from ..models import MyModel
from .fields import MyCustField

class MyCustField(serializers.CharField):
    """为 Model 中的自定义域额外写的自定义 Serializer Field"""

    def to_representation(self, obj):
        """将从 Model 取出的数据 parse 给 Api"""
        return obj

    def to_internal_value(self, data):
        """将客户端传来的 json 数据 parse 给 Model"""
        return json.loads(data.encode(‘utf-8‘))

class UserSerializer(serializers.ModelSerializer):

    class Meta:
        model = User  # 定义关联的 Model
        fields = (‘id‘, ‘username‘, ‘mymodels‘)  # 指定返回的 fields

    # 这句话的作用是为 MyModel 中的外键建立超链接,依赖于 urls 中的 name 参数
    # 不想要这个功能的话完全可以注释掉
    mymodels = serializers.HyperlinkedRelatedField(
        many=True, queryset=MyModel.objects.all(),
        view_name=‘model-detail‘
    )

class MySerializer(serializers.ModelSerializer):

    options = MyCustField(
        max_length=1000, style={‘base_template‘: ‘textarea.html‘},
    )

    class Meta:
        model = MyModel
        fields = (‘id‘, ‘owner‘, ‘field‘, ‘options‘)
        read_only_fields = (‘owner‘,)  # 指定只读的 field

    def create(self, validated_data):
        """响应 POST 请求"""
        # 自动为用户提交的 model 添加 owner
        validated_data[‘owner‘] = self.context[‘request‘].user
        return MyModel.objects.create(**validated_data)

    def update(self, instance, validated_data):
        """响应 PUT 请求"""
        instance.field = validated_data.get(‘field‘, instance.field)
        instance.save()
        return instance

ViewSet

定义好了 Serializers,就可以开始写 viewset 了

其实 viewset 反而是最简单的部分,rest_framework 原生提供了四种 ViewSet

  • ViewSet
  • GenericViewSet
    • 继承于 GenericAPIView
  • ModelViewSet
    • 自身提供了六种方法
    • list
    • create
    • retrieve
    • update
    • partial_update
    • destroy
  • ReadOnlyModelViewSet

我比较喜欢用 ModelViewSet,然后再用 Premissions 来管理权限

# myproject/myapp/views.py

#! /usr/bin/env python
# -*- coding: utf-8
from __future__ import unicode_literals, absolute_import

from django.contrib.auth.models import User
from rest_framework import permissions, viewsets, renderers
from rest_framework.decorators import (
    permission_classes, detail_route
)
from rest_framework.response import Response

from .serializers import MySerializer, UserSerializer
from .models import MyModel

class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    # 指定权限,下面马上讲到
    permission_classes = (permissions.IsAuthenticated,)

class ModelViewSet(viewsets.ModelViewSet):
    queryset = MyModel.objects.all()
    serializer_class = MySerializer
    permission_classes = (permissions.IsAuthenticatedOrReadOnly,)

    @detail_route(renderer_classes=[renderers.StaticHTMLRenderer])
    def plaintext(self, request, *args, **kwargs):
        """自定义 Api 方法"""
        model = self.get_object()
        return Response(repr(model))

我在 ModelViewSet 中自定义了方法 plaintext,rest_framework 中对于自定义的 viewset 方法提供了两种装饰器

  • list_route
  • detail_route

区别就是 list_route 的参数不包含 pk(对应 list),而 detail_route 包含pk(对应 retrieve)

看一段代码就懂了

@list_route(methods=[‘post‘, ‘delete‘])
def custom_handler(self, request):
    pass

@detail_route(methods=[‘get‘])
def custom_handler(self, request, pk=None):
    pass

Filters

前面根据 serializers 和 viewset 我们已经可以很好的提供数据接口和展示了。但是有时候我们需要通过 url参数 来对数据进行一些排序或过滤的操作,为此,rest-framwork 提供了 filters 来满足这一需求。

全局filter

可以在 settings 里指定应用到全局的 filter:

REST_FRAMEWORK = {
    ‘DEFAULT_FILTER_BACKENDS‘: (‘rest_framework.filters.DjangoFilterBackend‘,)
}

viewset 的 filter

也可以为 viewset 分别指定 filter,方法就是在定义 viewset 的时候定义一个名为filter_backend 的类变量:

class UserListView(generics.ListAPIView):
    queryset = User.objects.all()
    serializer = UserSerializer
    filter_backends = (filters.DjangoFilterBackend,)

默认的 filter

rest-framework 提供了几个原生的 filter:

  • SearchFilter
filter_backends = (filters.SearchFilter,)
search_fields = (‘username‘, ‘email‘)  # 指定搜索的域

请求 http://example.com/api/users?search=russell

  • OrderingFilter
filter_backends = (filters.OrderingFilter,)
ordering_fields = (‘username‘, ‘email‘)

请求 http://example.com/api/users?ordering=account,-username

自定义 filter

自定义 filter 非常简单,只需要定义 filter_queryset(self, request, queryset, view) 方法,并返回一个 queryset 即可。

直接贴一个我写的例子:

class NodenameFilter(filters.BaseFilterBackend):

    """根据 nodename 来删选
      [nodename]: NeiWang
    """

    def filter_queryset(self, request, queryset, view):
        nodename = request.QUERY_PARAMS.get(‘nodename‘)
        if nodename:
            return queryset.filter(nodename=nodename)
        else:
            return queryset

如果参数匹配有误,想要抛出异常的话,也可以自定义 APIError,举个例子:

from rest_framework.exceptions import APIException

class FilterError(APIException):
    status_code = 406
    default_detail = ‘Query arguments error!‘

然后在 viewset 里直接抛出 raise FilterError 即可。


Premissions

顾名思义就是权限管理,用来给 ViewSet 设置权限,使用 premissions 可以方便的设置不同级别的权限:

  • 全局权限控制
  • ViewSet 的权限控制
  • Method 的权限
  • Object 的权限

被 premission 拦截的请求会有如下的返回结果:

  • 当用户已登录,但是被 premissions 限制,会返回 HTTP 403 Forbidden
  • 当用户未登录,被 premissions 限制会返回 HTTP 401 Unauthorized

默认的权限

rest_framework 中提供了七种权限

  • AllowAny # 无限制
  • IsAuthenticated # 登陆用户
  • IsAdminUser # Admin 用户
  • IsAuthenticatedOrReadOnly # 非登录用户只读
  • DjangoModelPermissions # 以下都是根据 Django 的 ModelPremissions
  • DjangoModelPermissionsOrAnonReadOnly
  • DjangoObjectPermissions

全局权限控制

在 settings.py 中可以设置全局默认权限

# settings.py

REST_FRAMEWORK = {
    ‘DEFAULT_PERMISSION_CLASSES‘: (
        ‘rest_framework.permissions.AllowAny‘,
    ),
}

ViewSet 的权限

可以设置 permission_classes 的类属性来给 viewset 设定权限,restframework 会检查元组内的每一个 premission,必须要全部通过才行。

class UserViewSet(viewsets.ReadOnlyModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    # 设置权限,是一个元组
    permission_classes = (permissions.IsAuthenticated,)

自定义权限

Premissions 可以非常方便的定制,比如我就自己写了一个只允许 owner 编辑的权限

# myproject/myapp/premissions.py

#! /usr/bin/env python
# -*- coding: utf-8
from __future__ import unicode_literals, absolute_import

from rest_framework import permissions

class IsOwnerOrReadOnly(permissions.BasePermission):

    def has_permission(self, request, view):
        """针对每一次请求的权限检查"""
        if request.method in permissions.SAFE_METHODS:
            return True

    def has_object_permission(self, request, view, obj):
        """针对数据库条目的权限检查,返回 True 表示允许"""
        # 允许访问只读方法
        if request.method in permissions.SAFE_METHODS:
            return True

        # 非安全方法需要检查用户是否是 owner
        return obj.owner == request.user

urls & routers

# myproject/myapp/urls.py

#! /usr/bin/env python
# -*- coding: utf-8
from __future__ import unicode_literals, absolute_import

from django.conf.urls import url, patterns, include
from rest_framework.routers import DefaultRouter

from . import views

# as_view 方法生成 view
# 可以非常方便的指定 `{Http Method: View Method}`
user_detail = views.UserViewSet.as_view({‘get‘: ‘retrieve‘})
user_list = views.UserViewSet.as_view({‘get‘: ‘list‘, ‘post‘: ‘create‘})

# plaintext 是我的自定义方法,也可以非常方便的指定
modal_plain = views.ModelViewSet.as_view({‘get‘: ‘plaintext‘})
model_detail = views.ModelViewSet.as_view({‘get‘: ‘retrieve‘, ‘post‘: ‘create‘})
model_list = views.ModelViewSet.as_view({‘get‘: ‘list‘, ‘post‘: ‘create‘})

# router 的作用就是自动生成 Api Root 页面
router = DefaultRouter()
router.register(r‘models‘, views.ModelViewSet)
router.register(r‘users‘, views.UserViewSet)

# 不要忘了把 views 注册到 urls 中
urlpatterns = patterns(
    ‘‘,
    url(r‘^‘, include(router.urls)),  # Api Root
    url(r‘^api-auth/‘, include(‘rest_framework.urls‘, namespace=‘rest_framework‘)),
    url(r‘^models/(?P<pk>[0-9]+)/$‘, model_detail, name=‘model-detail‘),
    url(r‘^models/(?P<pk>[0-9]+)/plain/$‘, modal_plain, name=‘model-plain‘),
    url(r‘^models/$‘, model_list, name=‘model-list‘),
    url(r‘^users/$‘, user_list, name=‘user-list‘),
    url(r‘^users/(?P<pk>[0-9]+)/$‘, user_detail, name=‘user-detail‘),
)


时间仓促,就介绍这些,以后有空再介绍一下在 Django 用 JWT 作为身份凭证。下面是一些效果图

  • Api Root

  • Users


Reference

时间: 10-28

利用 Django REST framework 编写 RESTful API的相关文章

Django编写RESTful API(六):ViewSets和Routers

前言 在本系列的文章中,我在第一篇和第二篇文章中写的编写Django视图时,使用的都是基于函数的方法,并且每个视图函数之前都会加一个django-rest-framework带的装饰器@api_view.然后在第三篇文章,我们就开始把基于函数的视图改成了基于类的视图,然后发现这样做视图部分减少了很多代码量. 在这一篇文章中,我要介绍的是另一种基于类的视图的写法,它的抽象程度更高,也可以说是代码量又减少了.OK,废话不多说,先进入主题~ 使用ViewSets重构视图 先介绍一下这个ViewSets

Django编写RESTful API(三):基于类的视图

欢迎访问我的个人网站:www.comingnext.cn 前言 在上一篇文章中,主要讲的是请求和响应,项目里面views.py中的视图函数都是基于函数的,并且我们介绍了@api_view这个很有用的装饰器.同时,我们还介绍了APIView这个类,但是还没使用它.在这篇文章中,我们要做的是把基于方法的视图改为基于类的视图,将会了解到APIView. 改为基于类的视图 重构一下snippets/view.py: from snippets.models import Snippet from sni

Restful API官方文档

理解Restful架构:http://www.ruanyifeng.com/blog/2011/09/restful RESTful设计指南:http://www.ruanyifeng.com/blog/2014/05/restful_api.html Django REST framework文档:http://www.django-rest-framework.org/#installation Django RESTful 中文翻译:http://blog.csdn.net/ppppfly

构建自描述 RESTFul API 体系的设计与畅想

今天的互联网世界,API 已经无处不在,越来越多的服务依赖 API 交换信息,彼此协作,彼此连接,API 开发协作的体验也越来越重要. 有协作,就有沟通,显而易见的方法就是写文档,用文档描述 API 的用途,使用方法.但如何保持文档与代码的同步确是业界的千古难题,能做得到位的寥寥无几. 难道就真的没有方法了吗? 这就是本文的主题,构建自描述 RESTFul API 体系,如何通过自描述的 API 设计,抹除代码与文档的界限,一切皆代码. 何谓自描述 所谓的自描述,就是让 API 在提供具体的功能

django rest framework 入门

django rest framework 入门1-序列化 Serialization 分类: Python 2013-01-22 22:24 11528人阅读 评论(0) 收藏 举报 djangopythonrest framework ************************************ 广告时间: 海淘导航网站推荐:海淘库:http://www.haitaocool.com/ 需要的请收藏哦 ************************************ 1.

RESTful API的设计原则

最近一直在做公司的一个API平台的项目,前后大约有半年多了,中间穿插了好多其他的项目一起做的.上周经理要求写文档,我就重新打开项目开始检阅之前的代码,发现好多地方当初设计的并不合理,忽然就想到,一个好的API平台,应该怎么来设计呢?有哪些规范要遵守呢?面对自己的项目,感觉好多地方都要改,但是已经有人在用了,怎么办?全都要改动吗?所以就上网找解决方案,然后就发现一精品贴,现转载过来,以备不时查阅. 原文地址:http://www.cnblogs.com/moonz-wu/p/4211626.htm

flask开发restful api

在此之前,向大家说明的是,我们整个框架用的是flask + sqlalchemy + redis.如果没有开发过web,还是先去学习一下,这边只是介绍如果从开发web转换到开发移动端.如果flask还不是很熟悉,我建议先到这个网站简单学习一下,非常非常简单.http://dormousehole.readthedocs.org/en/latest/ 一直想写一些特别的东西,能让大家学习讨论的东西.但目前网上的很多博客,老么就按照官方文档照本宣读,要么直接搬代码,什么都不说明.我写这个系列的博客,

[CI] 使用CodeIgniter框架搭建RESTful API服务

在2011年8月的时候,我写了一篇博客<使用CodeIgniter框架搭建RESTful API服务>,介绍了RESTful的设计概念,以及使用CodeIgniter框架实现RESTful API的方法.转眼两年过去了,REST在这两年里有了很大的改进.我对于前一篇博客中的某些方面不是很满意,所以希望能利用这次机会写一个更加完善的版本.我的项目基于Phil Sturgeon的CodeIgniter REST Server,遵循他自己的DBAD协议.Phil的这个项目很棒,干净利落,简单实用,并

3.Spring Boot中使用Swagger2构建强大的RESTful API文档

原文:http://www.jianshu.com/p/8033ef83a8ed 由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这些终端会共用很多底层业务逻辑,因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端. 这样一来,我们的RESTful API就有可能要面对多个开发人员或多个开发团队:IOS开发.Android开发或是Web开发