快速入门

在这里我们创建一个简单的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"
        }
    ]
}

或者直接打开浏览器： 如果使用浏览器，请确保已经使用右上角的登录功能登录。

好极了，就是这么简单！