Django REST framework-教程05-Relationships and Hyperlinked 原创翻译
2017-09-28 11:48
495 查看
python技术交流群332680349,资源分享,技术交流。
目前我们的API中的关联用主键表示。在本教程的这一部分中,我们将改进API的内在关联方式和展示方式,使用超链接来进行关联。
这里应该注意两件事。首先,我们使用REST框架的reverse函数来返回合乎要求的的URL; 第二,URL模式是通过方便的名字来标识的,我们稍后会在这里声明snippets/urls.py。
与所有其他API端点不同,我们不想使用JSON展示请求的数据,而是用HTML呈现表示。REST框架提供了两种HTML渲染器样式,一种用于处理使用模板呈现的HTML,另一种用于处理预呈现的HTML。第二个渲染器是我们想用于此端点的渲染器。
在创建代码高亮视图时,我们需要考虑的另一件事是,我们不能使用现有的具体通用视图。我们不是返回一个对象实例,而是一个对象实例的属性。
代替使用具体的通用视图,我们将使用基类来展示实例对象,并创建我们自己的.get()方法。在你的snippets/views.py添加:
像往常一样,我们需要添加我们在URLconf中创建的新视图。我们将为我们的新API根添加一个url配置在snippets/urls.py:
然后添加代码片段高亮的一个url模式:
使用主键
在实体之间使用超链接。
在相关实体上使用唯一的标识字段。
使用相关实体的默认字符串表示形式。
将相关实体嵌套在上级字段内表示。
一些其他自定义表示。
REST框架支持所有这些样式,并且可以跨越前向或反向关系应用它们,或者将其应用于诸如通用外键之类的自定义管理器。
在这种情况下,我们希望在实体之间使用超链接样式。为了这样做,我们将修改我们的序列器来扩展HyperlinkedModelSerializer而不是现有的ModelSerializer。
在HyperlinkedModelSerializer与ModelSerializer有以下区别:
默认情况下不包括该id字段。
它包括一个url字段,使用HyperlinkedIdentityField。
关联使用HyperlinkedRelatedField,代替PrimaryKeyRelatedField。
我们可以轻松地重写我们现有的序列器以使用超链接。在你的snippets/serializers.py添加:
请注意,我们还添加了一个新的’highlight’字段。该字段与url字段的类型相同,只是它指向’snippet-highlight’url模式,而不是’snippet-detail’url模式。
因为我们已经包括格式后缀的URL例如 ‘.json’,所以我们还需要在highlight字段上指出任何格式后缀的超链接它应该使用’.html’后缀。
- 我们的API的根端点指向’user-list’和’snippet-list’。
- 我们的代码段串行器包括一个引用的字段’snippet-highlight’。
- 我们的用户串行器包括一个引用的字段’snippet-detail’。
- 我们的代码段和用户串行器序包括’url’默认情况下将引用的字段,按照’{model_name}-detail’格式,在这种情况下将是’snippet-detail’和’user-detail’。
将所有这些名字添加到我们的URL配置中后,我们的最终snippets/urls.py文件应该如下所示:
我们可以通过tutorial/settings.py稍微修改我们的文件来更改默认列表样式来使用分页。添加以下设置:
请注意,REST框架中的设置都将命名空间为单个字典设置,命名为“REST_FRAMEWORK”,这有助于保持与您的其他项目设置的良好分离。
我们也可以自定义分页风格,如果我们也需要,但在这种情况下,我们将坚持默认。
您还可以看到片段实例上的高亮链接,这将使您转到高亮的代码HTML表示。
在本教程的第6部分中,我们将介绍如何使用视图集合和路由器来减少构建API所需的代码量。
目前我们的API中的关联用主键表示。在本教程的这一部分中,我们将改进API的内在关联方式和展示方式,使用超链接来进行关联。
01-为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。
02-为高亮代码创建一个端点
我们的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中创建的新视图。我们将为我们的新API根添加一个url配置在snippets/urls.py:
url(r'^$', views.api_root),
然后添加代码片段高亮的一个url模式:
url(r'^snippets/(?P<pk>[0-9]+)/highlight/$', views.SnippetHighlight.as_view()),
03-为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’后缀。
04-确定我们的url模式被命名
如果我们要有一个超链接的API,我们需要确定我们的URL模式。我们来看看我们需要命名的URL模式。- 我们的API的根端点指向’user-list’和’snippet-list’。
- 我们的代码段串行器包括一个引用的字段’snippet-highlight’。
- 我们的用户串行器包括一个引用的字段’snippet-detail’。
- 我们的代码段和用户串行器序包括’url’默认情况下将引用的字段,按照’{model_name}-detail’格式,在这种情况下将是’snippet-detail’和’user-detail’。
将所有这些名字添加到我们的URL配置中后,我们的最终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') ]) # Login and logout views for the browsable API urlpatterns += [ url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')), ]
05-添加页码
用户和代码段的列表视图可能会返回相当多的实例,因此我们真的希望确保分页对于返回结果,并允许API客户端逐步浏览每个单独的页面。我们可以通过tutorial/settings.py稍微修改我们的文件来更改默认列表样式来使用分页。添加以下设置:
REST_FRAMEWORK = { 'PAGE_SIZE': 10 }
请注意,REST框架中的设置都将命名空间为单个字典设置,命名为“REST_FRAMEWORK”,这有助于保持与您的其他项目设置的良好分离。
我们也可以自定义分页风格,如果我们也需要,但在这种情况下,我们将坚持默认。
06-浏览API
如果我们打开浏览器并导航到可浏览的API,那么您可以通过以下链接了解API的工作方式。您还可以看到片段实例上的高亮链接,这将使您转到高亮的代码HTML表示。
在本教程的第6部分中,我们将介绍如何使用视图集合和路由器来减少构建API所需的代码量。
相关文章推荐
- Django REST framework-教程06-ViewSets and Routers 原创翻译
- django Rest Framework 系列 5 - Relationships & Hyperlinked APIs
- django rest framework 入门5——Relationships & Hyperlinked APIs
- Django REST framework-API指南05-ViewSets 原创翻译
- Django REST framework-教程00-quickstart原创翻译
- Django REST framework-API指南03-Class-based Views 原创翻译
- Django REST framework-API指南04-Generic views 原创翻译
- Django 之REST framework学习5:关联性和超链接API(Relationships & Hyperlinked APIs)
- Django REST framework-API指南02-Responses 原创翻译
- Django REST framework-API指南01-Requests 原创翻译
- python django rest framework Relationships & Hyperlinked APIs
- DxO PhotoLab 1 中文教程(原创翻译 260页)
- Django REST FrameWork中文教程2:请求和响应
- Django Rest Framework 教程及API向导
- Django REST FrameWork中文教程1:序列化
- Django REST framework教程三: 基于类的视图
- 原创翻译:Go, Ruby, Swift and Java: 是时候学习一门新的DevOps语言了吗?
- NSOperation and NSOperationQueue教程(翻译)
- [原创翻译]Java and XML, 3rd Edition :Preface
- Django REST framework 截图教程