GitHub Search Django REST framework

Tutorial 5: Relationships & Hyperlinked APIs

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

Creating an endpoint for the root of our 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中声名的别名来标识。

Creating an endpoint for the highlighted snippets

我们的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(r'^$', views.api_root),

然后为片段突出显示添加网址格式：

url(r'^snippets/(?P<pk>[0-9]+)/highlight/$', views.SnippetHighlight.as_view()),

Hyperlinking our 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后缀。

Making sure our URL patterns are named

如果我们要使用超链接API，我们需要确保命名为URL地址。 我们来看看我们需要命名的URL地址。

  • 我们的API的根引用'user-list'和'snippet-list'。
  • 我们的snippet序列化包含一个引用'snippet-highlight'的字段。
  • 我们的用户序列化程序包含一个引用'snippet-detail'的字段。
  • 我们的snippet和用户序列化程序包含'url'字段，默认情况下将引用'{model_name} -detail'，在这种情况下将是'snippet- detail'和'user-detail'。

将所有这些名称添加到我们的URLconf后，我们的最终snippets / urls.py文件应如下所示：

from django.conf.urls import url, include
from rest_framework.urlpatterns import format_suffix_patterns
from snippets import views

# API endpoints
urlpatterns = format_suffix_patterns([
    url(r'^$', views.api_root),
    url(r'^snippets/$',
        views.SnippetList.as_view(),
        name='snippet-list'),
    url(r'^snippets/(?P<pk>[0-9]+)/$',
        views.SnippetDetail.as_view(),
        name='snippet-detail'),
    url(r'^snippets/(?P<pk>[0-9]+)/highlight/$',
        views.SnippetHighlight.as_view(),
        name='snippet-highlight'),
    url(r'^users/$',
        views.UserList.as_view(),
        name='user-list'),
    url(r'^users/(?P<pk>[0-9]+)/$',
        views.UserDetail.as_view(),
        name='user-detail')
])

Adding pagination

用户和代码片段的列表视图最终可能会返回很多实例，因此我们确实希望确保对结果进行分页，并允许API客户端逐步浏览每个页面。

我们可以通过稍微修改tutorial / settings.py文件来更改默认列表样式以使用分页。 添加以下设置：

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 10
}

请注意，REST框架中的设置都被命名为单个字典设置，名为REST_FRAMEWORK，这有助于将它们与其他项目设置完全分开。

如果我们需要，我们也可以自定义分页样式，但在这种情况下，我们只会坚持使用默认值。

Browsing the API

如果我们打开浏览器并导航到可浏览的API，您会发现现在只需按照链接即可熟悉API。

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

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