关系和超链接 API

为 API 创建一个根路径

现在我们有 book 和 users 的路径，但是我们的 API 没有一个入口点。我们将使用一个常规的基于函数的视图和我们前面介绍的 @api_view 装饰器创建一个。在你的 myApp/apis.py 中添加：

# apis.py

from rest_framework.decorators import api_view
from rest_framework.response import Response
from rest_framework.reverse import reverse

@api_view(['GET'])
def api_root(request, format=None):
    return Response({
        'users': reverse('user-list', request=request, format=format),
        'books': reverse('book-list', request=request, format=format)
    })

这里应该注意两件事。首先，我们使用 REST 框架的 reverse 功能来返回完全限定的URL；第二，URL 模式是通过 name 来标识的，我们在 myApp/urls.py 中声明。

urlpatterns = [
    ......
    url(r'^api/$', apis.api_root),
  
    # 注意 name 的使用
    url(r'^api/users/$', apis.UserList.as_view(), name='user-list'),
    url(r'^api/books/$', apis.BookList.as_view(), name='book-list'),
    ......
]

现在我们 API 的根路径就是：http://127.0.0.1:8000/api/

我们将会看到：

{
    "books": "http://127.0.0.1:8000/api/books/",
    "users": "http://127.0.0.1:8000/api/users/"
}

超链接我们的 API

要在我们的 API 使用超链接，需要在我们的序列化器使用 HyperlinkedModelSerializer 而不是现有的 ModelSerializer。

HyperlinkedModelSerializer 与 ModelSerializer 有以下区别：

默认情况下不包括id字段。
它包含一个 url 字段，使用 HyperlinkedIdentityField，显示该对象的 API 链接。
关联关系使用 HyperlinkedRelatedField，而不是 PrimaryKeyRelatedField。

我们先改写我们的序列化器，在 myApp/serializers.py 中：

# serializers.py

from django.contrib.auth.models import User
from myapp.models import Book

from rest_framework import serializers


class BookSerializer(serializers.ModelSerializer):
    # book 所关联的 user 通过超链接来显示
    # 这个关联关系通过 view_name 指定，和 urls 中 name 对应
    owner = serializers.HyperlinkedRelatedField(
        view_name='user-detail', 
        read_only=True
        )

    class Meta:
        model = Book
        # 显示的字段加上 url
        fields = ('url', 'id', 'title', 'author', 'amount', 'owner')

class UserSerializer(serializers.ModelSerializer):
    # user 所关联的 book 用超链接来显示
    # 这个关联关系通过 view_name 指定，和 urls 中 name 对应
    # 一个 user 可以对应多个 book，所以 many=True
    # 最后申明该字段是只读
    books = serializers.HyperlinkedRelatedField(
        many=True, 
        view_name='book-detail', 
        read_only=True
        )

    class Meta:
        model = User
        # 显示的字段加上 url
        fields = ('url', 'id', 'username', 'books')

编写 urls.py：

from django.conf.urls import url
from django.contrib import admin
from django.conf.urls import include
from rest_framework.urlpatterns import format_suffix_patterns
from myapp import apis


urlpatterns = [
    url(r'^admin/', admin.site.urls),

    # API 根目录
    url(r'^api/$', apis.api_root),

    # 所有 user 的 API
    url(r'^api/users/$', apis.UserList.as_view(), name='user-list'),
    # 单个 user 的 API
    url(r'^api/users/(?P<pk>[0-9]+)/$', apis.UserDetail.as_view(), name='user-detail'),

    # 所有 book 的 API
    url(r'^api/books/$', apis.BookList.as_view(), name='book-list'),
    # 单个 book 的 API
    url(r'^api/book/(?P<pk>[0-9]+)/$', apis.BookDetail.as_view(), name='book-detail'),
]

# url 格式化
urlpatterns = format_suffix_patterns(urlpatterns)

# url 的登录退出功能
urlpatterns += [
    url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')),
]

现在我们看一个 book 的实例：

{
    "url": "http://127.0.0.1:8000/api/book/1/",
    "id": 1,
    "title": "book1",
    "author": "aythor1",
    "amount": 1,
    "owner": "http://127.0.0.1:8000/api/users/1/"
}

可以看到他自身 API 的链接和它的 owner 的链接。

下面是一个 user 的实例：

{
    "url": "http://127.0.0.1:8000/api/users/1/",
    "id": 1,
    "username": "diego",
    "books": [
        "http://127.0.0.1:8000/api/book/1/",
        "http://127.0.0.1:8000/api/book/2/",
        "http://127.0.0.1:8000/api/book/5/"
}

可见，关联的所有 book 都用链接显示出来。

添加分页

REST 框架自带分页功能，只需在 tutorial/settings.py 文件添加以下设置：

REST_FRAMEWORK = {
    'PAGE_SIZE': 1
}

请注意，REST 框架中的所有设置都放在一个名为 REST_FRAMEWORK的字典中，这有助于区分项目中的其他设置。