此文档为官方文档的翻译，原文地址：https://www.django-rest-framework.org/tutorial/5-relationships-and-hyperlinked-apis/

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

为 API 的根创建一个端点

现在我们有“snippets”和“users”的端点，但是我们没有单一的 API 入口点。为了创建一个，我们将使用视图函数+@api_view 装饰器。在snippets/views.py 中添加:

  1. from rest_framework.decorators import api_view
  2. from rest_framework.response import Response
  3. from rest_framework.reverse import reverse
  6. @api_view(['GET'])
  7. def api_root(request, format=None):
  8.     return Response({
  9.         'users': reverse('user-list', request=request, format=format),
  10.         'snippets': reverse('snippet-list', request=request, format=format)
  11.     })

这里应该注意两件事。首先，我们使用 REST 框架的reverse()函数来返回完全限定的 URL; 其次，URL 模式是通过方便的名称来识别的，稍后我们将在 snippets/urls.py中声明这些名称。

为高亮显示的代码片段创建端点

我们的 pastebin api 还缺少另一个明显的东西，那就是“代码高亮显示”端点。

与我们的所有其他 API 端点不同，我们不想使用 JSON，而只是提供一个 HTML 表示。REST 框架提供了两种样式的 HTML 渲染器，一种用于处理使用模板渲染的 HTML，另一种用于处理预渲染的 HTML。第二个渲染器是我们希望用于此端点的渲染器。

在创建代码高亮显示视图时，我们需要考虑的另一件事是，我们没有可以使用的现有具体的通用视图。我们不返回对象实例，而是返回对象实例的属性。

我们不用具体的通用视图，而将使用基类来表示实例，并创建自己的.get()方法。在你的snippets/views.py中添加：

  1. from rest_framework import generics
  2. from rest_framework.response import Response
  3. from rest_framework import renderers  # 引入渲染模块
  5. class SnippetHighlight(generics.GenericAPIView):
  6.     queryset = Snippet.objects.all()
  7.     renderer_classes = [renderers.StaticHTMLRenderer]  # 指定渲染器
  9.     def get(self, request, *args, **kwargs):
  10.         snippet = self.get_object()  # 获得当前对象
  11.         return Response(snippet.highlighted)  # 返回高亮代码

像往常一样，我们需要将已经创建的新视图添加到 URL配置中。

  1. path('', views.api_root),
  2. path('snippets/<int:pk>/highlight/', views.SnippetHighlight.as_view()),

为我的API做超链接

处理实体之间的关系是 Web API 设计中一个更具挑战性的方面。我们可以选择许多不同的方式来表达一段关系:

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

REST框架支持所有这些方式，并且可以将它们应用于正向或反向关系，也可以在诸如通用外键之类的自定义管理器上应用。

在这种情况下，我们希望在实体之间使用超链接方式。为此，我们将修改序列化器以扩展 HyperlinkedModelSerializer，而不是现有的 ModelSerializer。
HyperlinkedModelSerializer与 ModelSerializer有以下不同之处:

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

我们可以轻松地重写我们现有的序列化程序以使用超链接。在你的snippets/serializers.py中添加：

  1. class SnippetSerializer(serializers.HyperlinkedModelSerializer):
  2.     owner = serializers.ReadOnlyField(source='owner.username')
  3.     highlight = serializers.HyperlinkedIdentityField(view_name='snippet-highlight', format='html')
  5.     class Meta:
  6.         model = Snippet
  7.         fields = ('url', 'id', 'highlight', 'owner',
  8.                   'title', 'code', 'linenos', 'language', 'style')
  11. class UserSerializer(serializers.HyperlinkedModelSerializer):
  12.     snippets = serializers.HyperlinkedRelatedField(many=True, view_name='snippet-detail', read_only=True)
  14.     class Meta:
  15.         model = User
  16.         fields = ('url', 'id', 'username', 'snippets')

请注意，我们还添加了一个新的highlight字段。该字段与url字段的类型相同，不同之处在于它指向snippet-highlighturl模式，而不是snippet-detailurl模式。

因为我们已经包含了格式后缀的URL，例如.json，我们还需要在highlight字段上指明任何格式后缀的超链接，它应该使用.html后缀。

确保我们的 URL 模式被命名

如果我们要有一个超链接的 API，我们需要确保我们命名我们的 URL 模式。让我们来看看我们需要命名的 URL 模式。

  • 我们API的根路径用到了user-list和snippet-list。
  • 我们的SnippetSerializer包含一个指向snippet-highlight的字段。
  • 我们的UserSerializer包含了一个指向snippet-detail的字段。
  • 我们的SnippetSerializer和UserSerializer都包含了一个url字段，它默认指向 {model_name}-detail, 在我们的例子中就是snippet-detail和 user-detail。

将所有这些名称添加到我们的url配置中之后，我们的 snippets/urls.py 文件应该长这个样子：

  1. from django.urls import path
  2. from rest_framework.urlpatterns import format_suffix_patterns
  3. from snippets import views
  5. # API 端点
  6. urlpatterns = format_suffix_patterns([
  7.     path('', views.api_root),
  8.     path('snippets/', views.SnippetList.as_view(), name='snippet-list'),
  9.     path('snippets/<int:pk>/', views.SnippetDetail.as_view(), name='snippet-detail'),
  10.     path('snippets/<int:pk>/highlight/', views.SnippetHighlight.as_view(), name='snippet-highlight'),
  11.     path('users/', views.UserList.as_view(), name='user-list'),
  12.     path('users/<int:pk>/', views.UserDetail.as_view(), name='user-detail')
  13. ])

添加分页

用户和代码片段的列表视图最终可能会返回很多实例，因此我们确实要确保我们为结果分页，并允许API客户端逐步浏览每个页面。
我们可以通过稍微修改我们的tutorial/settings.py文件来更改默认列表样式以使用分页。添加以下设置：

  1. REST_FRAMEWORK = {
  2.     'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
  3.     'PAGE_SIZE': 10
  4. }

请注意，REST框架中的设置都放到了一个名为REST_FRAMEWORK的字典中，这有助于使它们与其他设置保持良好分离。

如果需要的话，我们还可以自定义分页样式，但在这个例子中，我们先使用默认设置。

浏览API

如果我们打开浏览器并导航到可浏览的API，您会发现现在可以通过下面的链接来围绕API进行操作。

您还可以在摘要实例上看到 highlight链接，这将带您进入高亮显示的代码HTML表示。

在本教程的第6部分中，我们将看看如何使用 viewset 和 Routers 来减少构建 API 所需的代码量。