Django REST framework 第五章 Relationships & Hyperlinked APIs

╄→гoц情女王★ 提交于 2020-01-12 17:24:22

到目前为止,API内部的关系是使用主键来代表的。在这篇教程中,我们将提高API的凝聚力和可发现性,通过在相互关系上使用超链接。

 

Creating an endpoint for the root of our API

现在,我们已经有了snippets和users的终端,但是没有一个单独的终端指向我们的API。使用之前常规的FBV方式和@api_view装饰器创建一个。在你的app的views文件内

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 framework的reverse方法来返回完全合格的URLs;其次URL模式由稍后在app的urls文件内申明的便利的名称标识。

 

Creating an endppoint for the highlighted snippets

另一个明显的问题是在我们的API中仍然缺失代码突出的端点。

不像之前写过的API端点,我们不想使用JSON,而是用网页的表现形式来替代。REST framework提供了2种风格的HTML转换,一种用于处理使用模板呈现的HTML,另一个用于处理预先呈现的HTML。第二种渲染器是我们愿意在这个端点使用的那个。

另外还有一件事需要考虑, 当创建代码高亮视图时,没有我们可以使用的集成通用的视图。我们不会返回一个对象实例,取而代之的是一个对象实例的属性。

展示实例我们将可以使用基础类代替集成通用的视图,然后创建get方法。在app的views文件中添加:

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)

跟之前一样,这里还需要添加新的URL跟视图绑定。为新的API根添加url模式在app内的urls文件中:

    path('', views.api_root),

然后添加新的url模式:

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

 

 

Hyperlinking our API

处理实体之间的关系是Web API设计中更具挑战性的方面之一。有很多不同的方式可供我们选择来表示这一关系。

a、使用主键

b、在实体间使用超链接

c、在相关实体上使用唯一的标识字段

d、使用相关实体的默认字符串表示形式

e、将相关实体嵌套在父表示中

f、一些其他的自定制的表示形式

REST framework 支持所有这些方式,并且可以将它们应用于正向反向关系,或者自定制的管理(比如通用的外键)

在这个事例中,我们更倾向于在实体间用超链接方式。为了能够实现,我们将要修改serializers来扩展HyperlinkedModelSerializer代替现有的ModelSerializer

1、默认不包含id字段

2、它包含一个url字段,使用HyperlinkedIdentityField

3、关系用PrimaryKeyRelatedField代替HyperlinkedRelatedField

用超链接可以很简单的重写已经存在的serializers,在app内的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'代替'snippet-detail'url模式。因为我们包含了格式化后缀的rul比如json,所以也需要在highlight字段上指出,它返回的任何格式化后缀的超链接都应该使用.html后缀。

 

Making sure our URL patterns are named

如果我们想要用超链接的API,需要确保ur已经命名。一起看一下那些url需要命名

a、引用'user-list'和'snippet-list'的根API

b、包含在snippet serializer中的一个字段引用'snippet-highlight'

c、包含在user serializer中的一个字段引用'snippet-detail'

d、默认的snippet和user serializers中包含url字段的,将引用'{model_name}-detail',在这个事例里将会是'snippet-detail''user-detail'

将这些名称全部加入url配置后,最终app 内的urls文件应该是这样的:

from app01 import views
from django.urls import path, include
from rest_framework.urlpatterns import format_suffix_patterns


app_name = 'app01'
urlpatterns = [
    path('snippets/', views.SnippetList.as_view(), name='snippet-list'),
    path('snippets/<int:pk>/', views.SnippetDetail.as_view(), name='snippet-detail'),
    path('users/', views.UserList.as_view(), name='user-list'),
    path('users/<int:pk>/', views.UserDetail.as_view(), name='user-detail'),
    path('snippets/<int:pk>/highlight/', views.SnippetHighlight.as_view(), name='snippet-highlight'),
    path('', views.api_root),
]
urlpatterns = format_suffix_patterns(urlpatterns)

 

 

Adding pagination

装有users和code的snippets的视图列表最终能返回许多实例,因此我们真的要确保对结果进行分页,允许的API客户端逐个遍历每一个独立的页面.

可以该变默认的列表样式以使用分页,通过稍微修改app内的settings文件:

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

 

注意,REST framework中所有的设定都命名在一个独立的字典REST_FRAMEWORK里,它帮助我们跟其他项目的设置很好的分离开。

如果必要的话,我们也可以定制分页形式,但在这个事例中只是处理默认的分页。

 

易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!