第五章 关系与超链接API

写在前面：
本文翻译于django rest framework官方文档，由于网上大多数django rest framework中文翻译文档都有较为多的删减行为，笔者在学习的时候就觉得不是太方便，故笔者将官方文档较为完善的为大家翻译下，仅供大家学习参考。

由于笔者文笔有限，若有写得不当之处，敬请各位同仁指出；若涉及到侵权，请联系笔者，笔者将立即删除。

现在，我们的API中的关系通过使用主键来表示，在教程的这一部分中，我们将通过使用超链接来改善关系的内聚性和可发现性。

1. 为我们的API创建一个根路径

现在我们的users和snippets都配上了路径了，但是我们没有一个单个的API的进入点。要创建一个，我们可以在一个常规的基于函数的视图和我们前面介绍的@api_view装饰器。我们现在将在views.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),
        'snippets': reverse('snippet-list', request=request, format=format)
    })

我们这里要注意两件事情。首先，我们使用REST Framework的reverse函数来返回完全限定的URL；第二，URL Patterns由便捷的模式来标识。

我们现在将我们新建的视图添加到URL Conf中，我们现在在snippets/urls.py中为我们的API根目录添加一个新的URL Conf

url(r'^$', views.api_root),

2. 超链接我们的API

处理外键之间的关系是Web API设计的一个更具挑战性的方面，我们可以选择多种不同的方式来表示关系。

• 使用主键
• 使用实体之间的超链接
• 在相关实体上使用唯一识别的slug字段
• 使用相关实体的默认的字符串表现形式
• 将相关实体嵌套在父表示中
• 一些其他的自定义表示

REST Framework支持所有的这些格式，并且可以跨前或反向关系来应用他们，或者将他们应用于诸如通用外键的自定义管理器。

我们现在在实体间使用超链接的样式，为了这样做，我们需要修改我们的序列化器以扩展HyperlinkedModelSerializer来代替已存在的ModelSerializer

对于HyperlinkedModelSerializer与ModelSerial有如下的差别：

• 默认情况下不包含id字段
• 它包含一个url字段，使用HyperlinkedIdentityField
• 关系使用HyperlinkedIdentityField，而不是PrimaryKeyRelatedField

我们可以轻松的重写我们现有的序列化程序来使用超链接，在我们的 snippets/serializers.py 中添加以下代码：

class SnippetSerializer(serializers.HyperlinkedModelSerializer):
    owner = serializers.ReadOnlyField(source='owner.username')
    highlight = serializers.HyperlinkedIdentityField(view_name='snippet-highlight', format='html')

    class Meta:
        model = Snippet
        fields = ('url', 'id', 'highlight', 'owner',
                  'title', 'code', 'linenos', 'language', 'style')


class UserSerializer(serializers.HyperlinkedModelSerializer):
    snippets = serializers.HyperlinkedRelatedField(many=True, view_name='snippet-detail', read_only=True)

    class Meta:
        model = User
        fields = ('url', 'id', 'username', 'snippets')

3. 确保我们的URL Patterns已命名

如果我们要有一个超链接的API，我们需要确保我们我们命名了我们的URL Patterns，我们来看看我们需要命名的URL Patterns

• 指向user-list和snippet-list的我们的API的根
• 用户的序列化虚包含一个引用snippet-detail的字段
• 默认情况下我们的user和snippet的序列化程序包含url字段，默认情况下将引用“{model_name}-detail”，在这样的情况下，我们要引用的就是snippet-detail和user-detail

将所有的这些添加到我们的URL Conf之后，我们的snippets/urls.py文件将是如下的样子：

from django.conf.urls import url, include
from rest_framework.urlpatterns import format_suffix_patterns
from snippets import views

# API的路径
urlpatterns = format_suffix_patterns([
    url(r'^$', views.api_root),
    url(r'^snippets/$',
        views.SnippetList.as_view(),
        name='snippet-list'),
    url(r'^snippets/(?P<pk>[0-9]+)/$',
        views.SnippetDetail.as_view(),
        name='snippet-detail'),
    url(r'^users/$',
        views.UserList.as_view(),
        name='user-list'),
    url(r'^users/(?P<pk>[0-9]+)/$',
        views.UserDetail.as_view(),
        name='user-detail')
])

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

4. 添加分页

user和snippet的列表视图最终可能会返回很多实例，我们希望确保分页结果，并允许API客户端逐步的浏览每个单独的页面

我们可以通过修改我们的 tutorial/settings.py 文件，将默认列表样式更改为使用和分页，添加如下的设置：

REST_FRAMEWORK = {
    "PAGE_SIZE": 10
}

我们可以注意到REST Framework的设置都命名为单个的字典设置，这有助于他们和其他的项目设置保持分离。

5. 下一步

在下一章，我们将介绍如何使用ViewSets和Routers来减少构建我们的API所需的代码量。