教程5 - 关系和超链接API
关系和超链接API
目前，我们的API中的关系是通过使用主键来表示的。在本教程的这一部分中，我们将改善API的内聚性和可发现性，通过使用超链接建立关系。
为我们的API的根目录创建一个端点
现在，我们有“snippets”和“users”的端点，但是我们没有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数来返回完全限定的URLs.。 其次，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中。我们将在snippets/urls.py中为新的API根添加url模式：
path('', views.api_root),
然后为片段高亮添加一个URL模式：
path('snippets/<int:pk>/highlight/', views.SnippetHighlight.as_view()),
超链接我们的API
处理实体之间的关系是Web API设计更具挑战性的方面之一。我们可以选择多种表示关系的方式:
- 使用主键。
- 在实体之间使用超链接。
- 在相关实体上使用唯一的标识段
slug字段。 - 使用相关实体的默认字符串表示形式。
- 将相关实体嵌套在父代表示中。
- 其他自定义表示.
REST框架支持所有这些样式，并且可以将它们应用于正向或反向关系， 或将其应用到自定义管理器中，例如通用外键。
在本例中，我们希望在实体之间使用超链接样式。为了这样做，我们将修改序列化程序以扩展HyperlinkedModelSerializer，而不是现有的ModelSerializer。
HyperlinkedModelSerializer与ModelSerializer有以下区别：
- 默认情况下不包含id字段
- 它包括使用
HyperlinkedIdentityField的url字段。 - 关系使用
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字段具有相同的类型,只是它指向snippe-thighlight url模式, 而不是snippet-detail url模式。
因为我们包含了带有格式后缀的URL，例如.json。我们还需要在highlight字段中指出，它返回的任何带有格式后缀的超链接都应使用.html后缀。
确保我们的URL模式被命名
如果我们要有一个超链接的API， 我们需要确保我们命名我们的URL模式， 让我们看看我们需要命名哪些URL模式。
- 我们的API的根引用
user-list和snippet-list。 - 我们的代码段序列化程序包含一个引用
snippet-highlight的字段。 - 我们的用户序列化程序包含一个引用
snippet-detail的字段。 - 我们的代码段和用户序列化程序包括
url字段，默认情况下将引用{model_name} -detai，在这种情况下，它们将是snippet-detail和user-detai
将所有这些名称添加到我们的URLconf中之后, 我们的最终snippets/urls.py文件应如下所示：
from django.urls import path
from rest_framework.urlpatterns import format_suffix_patterns
from snippets import views
# API 端点
urlpatterns = format_suffix_patterns([
path('', views.api_root),
path('snippets/',
views.SnippetList.as_view(),
name='snippet-list'),
path('snippets/<int:pk>/',
views.SnippetDetail.as_view(),
name='snippet-detail'),
path('snippets/<int:pk>/highlight/',
views.SnippetHighlight.as_view(),
name='snippet-highlight'),
path('users/',
views.UserList.as_view(),
name='user-list'),
path('users/<int:pk>/',
views.UserDetail.as_view(),
name='user-detail')
])
添加分页
用户和代码段的列表视图最终可能会返回很多实例, 所以我们真的想确保我们对结果进行分页, 并允许API客户端逐步浏览各个页面。
我们可以更改默认列表样式以使用分页，通过稍微修改我们的tutorial/settings.py文件。添加以下设置：
REST_FRAMEWORK = {
'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
'PAGE_SIZE': 10
}
请注意，REST框架中的设置都是以名称空间命名的，并且是一个字典设置, 它命名为 REST_FRAMEWORK. 这有助于使它们与您的其他项目设置完全分开。
如果需要，我们也可以自定义分页样式，但是在这种情况下，我们将坚持使用默认样式。
浏览API
如果我们打开浏览器并导航到可浏览的API，您会发现您现在只需按以下链接即可使用API。
你还可以看到snippet实例上的“highlight”链接，这将带您到突出显示的代码HTML表示形式。
在本教程的第6部分中，我们将介绍如何使用ViewSet和Router减少构建API所需的代码量。
