在这里我们创建一个简单的 API，允许管理员查看、编辑用户和组信息。

项目设置

新建名为tutorial的 django 项目并在其中建立一个名为quickstart的 APP：

# 新建目录
mkdir tutorial
cd tutorial

# 新建虚拟环境
python3 -m venv env
source env/bin/activate  # Windows平台使用 `env\Scripts\activate`

# 在虚拟环境中安装依赖
pip install django
pip install djangorestframework

# 新建项目
django-admin startproject tutorial .  # 注意最后面的 '.'
cd tutorial
django-admin startapp quickstart
cd ..

此时目录结构应该如下所示：

$ 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

应用程序是在项目目录中创建的，这看起来很不寻常。使用项目的命名空间避免了与外部模块的名称冲突(这是一个超出“快速入门”范围的主题)。

使用下面的命令初始化数据库：

python manage.py migrate

然后创建一个用户名为admin密码为password123的管理员：

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

以上设置完成后，进入 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 rest_framework import permissions
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
    permission_classes = [permissions.IsAuthenticated]


class GroupViewSet(viewsets.ModelViewSet):
    """
    API endpoint that allows groups to be viewed or edited.
    """
    queryset = Group.objects.all()
    serializer_class = GroupSerializer
    permission_classes = [permissions.IsAuthenticated]

我们把许多常见的操作都封装在了类ViewSets中，这样就不用编写重复代码了。当然你可以按照自己的需求编写 view，但使用ViewSets可以保持 view 代码的简洁以及逻辑的清晰。

URLs

接下来编写tutorial/urls.py：

from django.urls import include, path
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 = [
    path('', include(router.urls)),
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

因为我们使用了ViewSets，所以我们可以通过使用 Router 类来自动生成 URL 配置信息。

重申一次，如果需要更自主的配置 URL，可以使用常规的类视图以及显式编写 URL 配置。

最后我们添加了默认的登录、登出视图在浏览 API 时候使用，这是一个可选项，但如果你想在浏览 API 时使用认证功能这是非常有用的。

Pagination

分页使您可以控制每页返回多少对象。为了启用它，将以下行添加到 tutorial/settings.py：

REST_FRAMEWORK = {
    'DEFAULT_PERMISSION_CLASSES': ('rest_framework.permissions.IsAdminUser',),
    'PAGE_SIZE': 10
}

Settings

将'rest_framework'到INSTALLED_APPS，该配置位于tutorial/settings.py：

INSTALLED_APPS = (
    ...
    'rest_framework',
)

至此，我们完成了全部工作。

测试

现在我们来测试我们的 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": "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 (opens new window) 命令行工具：

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"
        }
    ]
}
    

或者直接打开浏览器：

如果使用浏览器，请确保已经使用右上角的登录功能登录。

好极了，就是这么简单！

如果您想更深入地了解 REST 框架如何组合在一起，请继续阅读本教程 ，或者开始浏览 API 指南。