教程5：关系和超链接API
目前我们的API中的关系是使用主键表示的。在本教程的这一部分中，我们将通过使用超链接建立关系来提高API的内聚性和可发现性。
为我们的API的根创建端点
现在我们有“片段”和“用户”的端点，但我们的API没有单一的入口点。要创建一个，我们将使用基于函数的常规视图和@api_view我们之前介绍的装饰器。在你的snippets/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框架的reverse函数来返回完全限定的URL; 第二，URL模式由便利名称标识，稍后我们将在后面声明snippets/urls.py。
为突出显示的代码段创建端点
我们的pastebin API中仍然缺少的另一个显而易见的事情是代码突出显示端点。
与我们所有其他API端点不同，我们不想使用JSON，而只是呈现HTML表示。REST框架提供了两种HTML呈现器样式，一种用于处理使用模板呈现的HTML，另一种用于处理预呈现的HTML。第二个渲染器是我们要用于此端点的渲染器。
在创建代码突出显示视图时，我们需要考虑的另一件事是，我们可以使用现有的具体通用视图。我们不返回对象实例，而是返回对象实例的属性。
我们将使用基类来表示实例，而不是使用具体的通用视图，并创建我们自己的.get()方法。在你的snippets/views.py添加中：
from rest_framework import renderers
from rest_framework.response import Response
class SnippetHighlight(generics.GenericAPIView):
queryset = Snippet.objects.all()
renderer_classes = (renderers.StaticHTMLRenderer,)
def get(self, request, *args, **kwargs):
snippet = self.get_object()
return Response(snippet.highlighted)
像往常一样，我们需要将我们创建的新视图添加到URLconf中。我们将为新的API根添加一个url模式snippets/urls.py：
url('', views.api_root),
然后为片段突出显示添加网址格式：
url('snippets//highlight/', views.SnippetHighlight.as_view()),
超链接我们的API
处理实体之间的关系是Web API设计中更具挑战性的方面之一。我们可以选择多种不同的方式来表示关系：
- 使用主键。
- 在实体之间使用超链接。
- 在相关实体上使用唯一标识段塞字段。
- 使用相关实体的默认字符串表示形式。
- 将相关实体嵌套在父表示中。
- 一些其他自定义表示。
REST框架支持所有这些样式，并且可以跨正向或反向关系应用它们，或者将它们应用于自定义管理器（如通用外键）。
在这种情况下，我们想在实体之间使用超链接样式。为了做到这一点，我们将修改我们的序列化器来扩展HyperlinkedModelSerializer而不是现有的ModelSerializer。
在HyperlinkedModelSerializer有以下区别ModelSerializer：
-
id默认情况下不包括该字段。 - 它包括一个
url字段，使用HyperlinkedIdentityField。 - 关系使用
HyperlinkedRelatedField，而不是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')
请注意，我们还添加了一个新'highlight'字段。此字段与url字段的类型相同，只是它指向'snippet-highlight'url模式，而不是'snippet-detail'url模式。
因为我们已经包含格式后缀的URL '.json'，我们还需要在highlight字段上指明它返回的任何格式后缀超链接都应该使用'.html'后缀。
确保我们的URL模式已命名
如果我们要使用超链接API，我们需要确保命名我们的URL模式。我们来看看我们需要命名的URL模式。
- 我们的API的根是指
'user-list'和'snippet-list'。 - 我们的代码段序列化程序包含一个引用的字段
'snippet-highlight'。 - 我们的用户序列化程序包含一个引用的字段
'snippet-detail'。 - 我们的代码段和用户序列化程序包含
'url'默认情况下将引用的字段，'{model_name}-detail'在本例中为'snippet-detail'和'user-detail'。
将所有这些名称添加到我们的URLconf后，我们的最终snippets/urls.py文件应如下所示：
from django.urls import path
from rest_framework.urlpatterns import format_suffix_patterns
from snippets import views
# API endpoints
urlpatterns = format_suffix_patterns([
url(r'^snippets/(?P[0-9]+)/highlight/$', views.SnippetHighlight.as_view(),name='snippet-highlight'),
url(r'^snippets/(?P[0-9]+)/$', views.SnippetDetail.as_view(),name='snippet-detail'),
url(r'^snippets/$', views.SnippetList.as_view(),name='snippet-list'),
url(r'^users/(?P[0-9]+)/$', views.UserDetail.as_view(),name='user-detail'),
url(r'^users/$', views.UserList.as_view(),name='user-list'),
url('', views.api_root),
])
模型添加字段
class Snippet(models.Model):
created = models.DateTimeField(auto_now_add=True)
title = models.CharField(max_length=100, blank=True, default='')
code = models.TextField()
linenos = models.BooleanField(default=False)
language = models.CharField(choices=LANGUAGE_CHOICES, default='python', max_length=100)
style = models.CharField(choices=STYLE_CHOICES, default='friendly', max_length=100)
owner = models.ForeignKey('auth.User', related_name='snippets', on_delete=models.CASCADE)
highlighted = models.TextField()
class Meta:
ordering = ('created', )
def save(self, *args, **kwargs):
"""
Use the `pygments` library to create a highlighted HTML
representation of the code snippet.
"""
lexer = get_lexer_by_name(self.language)
linenos = self.linenos and 'table' or False
options = self.title and {'title': self.title} or {}
formatter = HtmlFormatter(
style=self.style, linenos=linenos, full=True, **options)
self.highlighted = highlight(self.code, lexer, formatter)
super(Snippet, self).save(*args, **kwargs)
添加分页
用户和代码片段的列表视图最终可能会返回很多实例，因此我们确实希望确保对结果进行分页，并允许API客户端逐步浏览每个页面。
我们可以通过tutorial/settings.py稍微修改我们的文件来更改默认列表样式以使用分页。添加以下设置：
REST_FRAMEWORK = {
'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
'PAGE_SIZE': 10
}
请注意，REST框架中的设置都被命名为单个字典设置，命名为REST_FRAMEWORK，这有助于将它们与其他项目设置完全分开。
如果我们需要，我们也可以自定义分页样式，但在这种情况下，我们只会坚持使用默认值。
测试API
api root
User List