快速入门
在这里我们创建一个简单的API,让管理员查看、编辑用户和组信息。
项目设置
新建名为tutorial
的django项目并在其中建立一个名为quickstart
的APP:
# 新建目录
mkdir tutorial
cd tutorial
# 新建虚拟环境
virtualenv env
source env/bin/activate # Windows使用 `env\Scripts\activate`
# 在虚拟环境中安装依赖
pip install django
pip install djangorestframework
# 新建项目
django-admin.py startproject tutorial . # 注意后面的 '.'
cd tutorial
django-admin.py startapp quickstart
cd ..
使用下面的命令创建表:
python manage.py migrate
然后创建一个用户名为admin
密码password123
的管理员:
python manage.py createsuperuser
以上设置完成后,进入APP的目录来编写代码...
序列化
首先我们创建一个文件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
来建立超链接关系,你也可以使用主键或其他关系,但hyperlinking是一个好的RESTful设计。
Views
现在让我们来编写视图文件tutorial/quickstart/views.py
:
from django.contrib.auth.models import User, Group
from rest_framework import viewsets
from tutorial.quickstart.serializers import UserSerializer, GroupSerializer
class UserViewSet(viewsets.ModelViewSet):
"""
查看、编辑用户的界面
"""
queryset = User.objects.all().order_by('-date_joined')
serializer_class = UserSerializer
class GroupViewSet(viewsets.ModelViewSet):
"""
查看、编辑组的界面
"""
queryset = Group.objects.all()
serializer_class = GroupSerializer
我们把许多常见的操作都封装在了类ViewSets
中,这样就不用编写重复代码了。当然你可以按照自己的需求编写view,但使用ViewSets
可以保持view代码的简洁以及逻辑的清晰。
URLs
接下来编写tutorial/urls.py
:
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)
# 使用URL路由来管理我们的API
# 另外添加登录相关的URL
urlpatterns = [
url(r'^', include(router.urls)),
url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]
因为我们使用了ViewSets
,所以我们可以通过使用Router类来自动生成URL配置信息。
重申一次,如果需要更自主的配置URL,可以使用常规的类视图以及显式编写URL配置。
最后我们添加了默认的登录、登出视图在浏览API时候使用,这是一个可选项,但如果你想在浏览API时使用认证功能这是非常有用的。
Settings
我们还需要进行一些全局设置。我们想启用分页功能以及只有管理员能访问,编辑tutorial/settings.py
:
INSTALLED_APPS = (
...
'rest_framework',
)
REST_FRAMEWORK = {
'DEFAULT_PERMISSION_CLASSES': ('rest_framework.permissions.IsAdminUser',),
'PAGE_SIZE': 10
}
至此,我们完成了全部工作。
测试
现在我们来测试我们的API,在终端中输入:
python ./manage.py runserver
现在我们可以使用命令行工具访问API了,比如curl
:
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": "[email protected]",
"groups": [],
"url": "http://127.0.0.1:8000/users/1/",
"username": "admin"
},
{
"email": "[email protected]",
"groups": [ ],
"url": "http://127.0.0.1:8000/users/2/",
"username": "tom"
}
]
}
或者httpie
http -a admin:password123 http://127.0.0.1:8000/users/
HTTP/1.1 200 OK
...
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"email": "[email protected]",
"groups": [],
"url": "http://localhost:8000/users/1/",
"username": "paul"
},
{
"email": "[email protected]",
"groups": [ ],
"url": "http://127.0.0.1:8000/users/2/",
"username": "tom"
}
]
}
或者直接打开浏览器:
如果使用浏览器,请确保已经使用右上角的登录功能登录。
好极了,就是这么简单!