第06篇 关系和超链接 API

教程 5：关系和超链接 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函数来返回完全限定的 URL；其次，URL 模式由我们稍后将在snippets/urls.py.

为突出显示的片段创建端点

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

与我们所有其他 API 端点不同，我们不想使用 JSON，而只是呈现 HTML 表示。REST framework 提供了两种样式的 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 中。我们将为我们的新 API 根添加一个 url 模式snippets/urls.py：

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'and '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 部分中，我们将了解如何使用 ViewSet 和路由器来减少构建 API 所需的代码量。