django rest framework quickstart

翻译自django rest framework官方文档, 版本3.1,原文地址http://www.django-rest-framework.org/

Quickstart

我们将创建一个简单的API来允许管理员用户查看和修改系统用户和组.

Project setup

创建一个新的django project叫tutorial,然后创建一个新app叫quickstart.

# 创建工程目录
mkdir tutorial
cd tutorial

# 在本地创建一个virtualenv来孤立依赖包
virtualenv env
source env/bin/activate # 在windows中使用 'env\Scripts\active'

# 在virtualenv中安装django和django REST framework
pip install django
pip install djangorestframework

# 创建一个工程,只有一个应用
django-admin.py startproject tutorial.  # 注意结尾的"."字符(注:这是什么意思,我也不知道)
cd tutorial
django-admin.py startapp quickstart
cd ..

然后首次同步数据库:

python manage.py migrate

然后创建一个初始化用户名字是admin,密码是passwor.我们将会在例子里验证这个用户.

python manage.py createsuperuser

如果你已经安装了数据库并且创建了初始化用户,打开应用目录,开始写代码…

Serializers

首先我们要定义一些序列化器.创建一个新模块叫tutorial/quickstart/serializers.py,表示我们要使用的数据

from django.contrib.auth.models import User, Group
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')

注意,我们在这个例子里通过HyperlinkedModelSerializer使用了hyperlinked关联.你也可以使用主键或者其他关联,但hyperlinked适合RESTful设计.

Views

好了,我们接下来写一些视图.打开tutorial/quickstart/views开始写代码.

from django.contrib.auth.models import User, Group
from rest_framework import viewsets
from tutorial.quickstart.serializers import UserSerializer, GroupSerializer

class UserViewSet(viewsets.ModelViewSet):
    '''
    API端,允许查看和编辑users
    '''
    queryset = User.objects.all()
    serializer_class = UserSerializer

class GroupViewSet(viewsets.ModelViewSet):
    '''
    API端,允许查看和编辑groups
    '''
    queryset = Group.objects.all()
    serializer_class = GroupSerializer

我们把一些通用操作一起封装到了ViewSets里,而不用写很多views.
如果有需要的话,我们可以很容易的把他们分成许多views,但是使用viewsets能很好的组织视图逻辑,保持简练.
在某些情况下,你可以很容易地设置ViewSet类的model属性,serializer和queryset就会自动的生成.设置queryset或serializer_class属性能使你更显式控制API的
行为,这也是大多数应用推荐的方式.

URLS

OK,现在让我们配置API的URL,请看tutorial/urls.py…

from django.conf.url import url, include
from rest_framework import routers
from tutorial.quickstart import views

router = router.DefaultRouter()
router.register(r'Users', views.UserViewSet)
router.register(r'groups', 'views.GroupViewSet')

# 使用自动化URL routing配置API
# 另外,还需要可浏览的API的登录用的URL
urlpatterns = [
    url(r'^', include(router.urls)),
    url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

因为我们使用的是viewsets而不是views,所以我们很简单的在router类里注册viewsets就可以为API自动生成URL配置.
如果我们需要对API URL更多的控制,我们可以很容易的不使用这些,而是直接使用views,并且显式的写URL配置.
最后,API的浏览控制需要默认的登录和注销views.这是可选的,但是如果你的API需要认证,而且你想使用API浏览控制,就很必要了.

Settings

我们还要做一些全局设置.我们会想要翻页,想要不只是管理员用户使用API.settings模块在tutorial/settings.py里

INSTALL_APPS = (
    ...
    'rest_frameword',
)

REST_FRAMEWORD = {
    'DEFAULT_PERMISSION_CLASSES': ('rest_framework.permissions.ISAdminUser'),
    'PAGE_SIZE': 10
}

OK,我们完成了

Testing our API

我们准备要测试我们创建的API了,让我们通过命令行来启动服务器.

python ./manage.py runserver

我们可以在命令行里使用想curl这样的工具来访问API,…

bash:curl -H 'Accept:application/json;indent=4' -u admin:password http://127.0.0.1:8000/users/
{
    "count": 2,
    "next": null,
    "previous": null,
    "result":[
        {
            "email": "admin@example.com",
            "groups":[],
            "url": "http://127.0.0.1:8000/users/1/",
            "username": "admin"
        },

        {
            "email": "tom@example.com",
            "groups":[],
            "url": "http://127.0.0.1:8000/users/2/",
            "username": "tom"
        }
    ]
}

或者命令行工具httpie

bash: http -a username:password http://127.0.0.1:8000/users/

HTTP/1.1 200 OK
...
{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "email": "admin@example.com",
            "groups": [],
            "url": "http://localhost:8000/users/1/",
            "username": "paul"
        },
        {
            "email": "tom@example.com",
            "groups": [],
            "url": "http://127.0.0.1:8000/users/2/",
            "username": "tom"
        }
    ]
}

或者直接使用浏览器
如果你使用的是浏览器,确保使用右上角的control先登录.