快速入门

我们会创建一套简单的API来允许管理员查看和编辑系统中的用户和用户组

创建项目

创建一个新的Django项目tutorial,然后创建一个新的appquickstart

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Create the project directory
mkdir tutorial
cd tutorial
# Create a virtualenv to isolate our package dependencies locally
virtualenv env
source env/bin/activate # On Windows use `env\Scripts\activate`
# Install Django and Django REST framework into the virtualenv
pip install django
pip install djangorestframework
# Set up a new project with a single application
django-admin.py startproject tutorial . # Note the trailing '.' character
cd tutorial
django-admin.py startapp quickstart
cd ..

项目的结果应该像这样:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
$ pwd
<some path>/tutorial
$ find .
.
./manage.py
./tutorial
./tutorial/__init__.py
./tutorial/quickstart
./tutorial/quickstart/__init__.py
./tutorial/quickstart/admin.py
./tutorial/quickstart/apps.py
./tutorial/quickstart/migrations
./tutorial/quickstart/migrations/__init__.py
./tutorial/quickstart/models.py
./tutorial/quickstart/tests.py
./tutorial/quickstart/views.py
./tutorial/settings.py
./tutorial/urls.py
./tutorial/wsgi.py

这看起来可能有些不寻常,在项目目录中创建了应用程序。使用项目命名空间避免扩展模块的命名冲突。

现在第一次同步你的数据库:

1
python manage.py migrate

我们还将创建一个初始用户user,密码是password123。在稍后的例子中我们会认证该用户。

1
python manage.py createsuperuser --email admin@example.com --username admin

一旦你建立一个数据库和一个初始用户并且已经准备好,打开app目录然后开始敲码…

序列化器

首先我们会定义一些序列号器。让我创建一个新的模块tutorial/quickstart/serializers.py我们将会使用它们来表示我们的数据。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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。你也可以使用主键和其他关系,但是超链接是良好的RESTful设计。

视图

是的,我们最好写一些视图。打开tutorial/quickstart/views.py然后输入:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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 endpoint that allows users to be viewed or edited.
"""
queryset = User.objects.all().order_by('-date_joined')
serializer_class = UserSerializer
class GroupViewSet(viewsets.ModelViewSet):
"""
API endpoint that allows groups to be viewed or edited.
"""
queryset = Group.objects.all()
serializer_class = GroupSerializer

我们不是写许多视图,而是将所有常见的行为分组成类ViewSets

如果我们需要,我们可以很容易的把这些分解为单独的视图,但是使用viewsets维护视图逻辑易于管理也非常简洁。

URLs

Okay,现在让我将API接到URLs。打开tutorial/urls.py

1
2
3
4
5
6
7
8
9
10
11
12
13
14
from django.conf.urls import url, include
from rest_framework import routers
from tutorial.quickstart import views
router = routers.DefaultRouter()
router.register(r'users', views.UserViewSet)
router.register(r'groups', views.GroupViewSet)
# Wire up our API using automatic URL routing.
# Additionally, we include login URLs for the browsable API.
urlpatterns = [
url(r'^', include(router.urls)),
url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

因为我们使用viewsets代替普通的视图,所以通过简单地将viewsets注册为一个路由类,我们可以为我们API自动地生成URL配置。

如果我们需要对API URLs有更多操作,我们可以使用普通的视图并且明确地编写URL配置文件。

最后,我们通过browsable API包含了默认的登陆和注销视图。这是可选的,但是如果你的API需要认证功能和你想使用browsable API,这将非常有用。

设置

rest_framework添加到INSTALLED_APPS。设置模块在tutorial/settings.py

1
2
3
4
INSTALLED_APPS = (
...
'rest_framework',
)

Okay,我们完成了。


测试我们的API

我们现在准备测试我们刚刚创建的API。让我们通过命令行启动服务器。

1
python manage.py runserver

我们可以访问我们的API,通过命令行或者使用工具:curl…

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
bash: curl -H 'Accept: application/json; indent=4' -u admin:password123 http://127.0.0.1:8000/users/
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"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,命令行工具…

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
bash: http -a admin:password123 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"
}
]
}

或者直接使用浏览器访问http://127.0.0.1:8000/users/

如果你使用浏览器,首先确保你已经通过右上角登陆。

好的,就是这么简单!

如果你想更深入了解,可以浏览API guide

原文:http://www.django-rest-framework.org/tutorial/quickstart/#quickstart

留言

⬆︎TOP