教程 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 中稍后声明这些名称。

为突出显示的代码片段创建一个端点

我们的粘贴 API 中仍然缺少的另一个明显的东西是代码突出显示端点。

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

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

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

from rest_framework import renderers

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 字段。
它包含一个 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([
    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 中进行操作。

您还可以在代码段实例上看到“突出显示”链接，该链接将带您到突出显示的代码 HTML 表示。

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