第五章 关系与超链接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所需的代码量。
