到目前为止,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里,它帮助我们跟其他项目的设置很好的分离开。
如果必要的话,我们也可以定制分页形式,但在这个事例中只是处理默认的分页。
来源:https://www.cnblogs.com/wuzdandz/p/9462802.html