Tutorial 5: Relationships & Hyperlinked APIs
转载自:http://www.django-rest-framework.org/tutorial/5-relationships-and-hyperlinked-apis/
Tutorial 5: Relationships & Hyperlinked APIs
At the moment relationships within our API are represented by using primary keys. In this part of the tutorial we'll improve the cohesion and discoverability of our API, by instead using hyperlinking for relationships.
Creating an endpoint for the root of our API
Right now we have endpoints for 'snippets' and 'users', but we don't have a single entry point to our API. To create one, we'll use a regular function-based view and the @api_view
decorator we introduced earlier. In your snippets/views.py
add:
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)
})
Two things should be noticed here. First, we're using REST framework's reverse
function in order to return fully-qualified URLs; second, URL patterns are identified by convenience names that we will declare later on in our snippets/urls.py
.
Creating an endpoint for the highlighted snippets
The other obvious thing that's still missing from our pastebin API is the code highlighting endpoints.
Unlike all our other API endpoints, we don't want to use JSON, but instead just present an HTML representation. There are two styles of HTML renderer provided by REST framework, one for dealing with HTML rendered using templates, the other for dealing with pre-rendered HTML. The second renderer is the one we'd like to use for this endpoint.
The other thing we need to consider when creating the code highlight view is that there's no existing concrete generic view that we can use. We're not returning an object instance, but instead a property of an object instance.
Instead of using a concrete generic view, we'll use the base class for representing instances, and create our own .get()
method. In your snippets/views.py
add:
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)
As usual we need to add the new views that we've created in to our URLconf. We'll add a url pattern for our new API root in snippets/urls.py
:
url(r'^$', views.api_root),
And then add a url pattern for the snippet highlights:
url(r'^snippets/(?P<pk>[0-9]+)/highlight/$', views.SnippetHighlight.as_view()),
Hyperlinking our API
Dealing with relationships between entities is one of the more challenging aspects of Web API design. There are a number of different ways that we might choose to represent a relationship:
- Using primary keys.
- Using hyperlinking between entities.
- Using a unique identifying slug field on the related entity.
- Using the default string representation of the related entity.
- Nesting the related entity inside the parent representation.
- Some other custom representation.
REST framework supports all of these styles, and can apply them across forward or reverse relationships, or apply them across custom managers such as generic foreign keys.
In this case we'd like to use a hyperlinked style between entities. In order to do so, we'll modify our serializers to extend HyperlinkedModelSerializer
instead of the existing ModelSerializer
.
The HyperlinkedModelSerializer
has the following differences from ModelSerializer
:
- It does not include the
id
field by default. - It includes a
url
field, usingHyperlinkedIdentityField
. - Relationships use
HyperlinkedRelatedField
, instead ofPrimaryKeyRelatedField
.
We can easily re-write our existing serializers to use hyperlinking. In your snippets/serializers.py
add:
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')
Notice that we've also added a new 'highlight'
field. This field is of the same type as the url
field, except that it points to the 'snippet-highlight'
url pattern, instead of the 'snippet-detail'
url pattern.
Because we've included format suffixed URLs such as '.json'
, we also need to indicate on the highlight
field that any format suffixed hyperlinks it returns should use the '.html'
suffix.
Making sure our URL patterns are named
If we're going to have a hyperlinked API, we need to make sure we name our URL patterns. Let's take a look at which URL patterns we need to name.
- The root of our API refers to
'user-list'
and'snippet-list'
. - Our snippet serializer includes a field that refers to
'snippet-highlight'
. - Our user serializer includes a field that refers to
'snippet-detail'
. - Our snippet and user serializers include
'url'
fields that by default will refer to'{model_name}-detail'
, which in this case will be'snippet-detail'
and'user-detail'
.
After adding all those names into our URLconf, our final snippets/urls.py
file should look like this:
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')),
]
Adding pagination
The list views for users and code snippets could end up returning quite a lot of instances, so really we'd like to make sure we paginate the results, and allow the API client to step through each of the individual pages.
We can change the default list style to use pagination, by modifying our tutorial/settings.py
file slightly. Add the following setting:
REST_FRAMEWORK = {
'PAGE_SIZE': 10
}
Note that settings in REST framework are all namespaced into a single dictionary setting, named 'REST_FRAMEWORK', which helps keep them well separated from your other project settings.
We could also customize the pagination style if we needed too, but in this case we'll just stick with the default.
Browsing the API
If we open a browser and navigate to the browsable API, you'll find that you can now work your way around the API simply by following links.
You'll also be able to see the 'highlight' links on the snippet instances, that will take you to the highlighted code HTML representations.
In part 6 of the tutorial we'll look at how we can use ViewSets and Routers to reduce the amount of code we need to build our API.
Tutorial 5: Relationships & Hyperlinked APIs的更多相关文章
- 05_Tutorial 5: Relationships & Hyperlinked APIs 关系和超链接
1.关系和超链接 0.文档 https://www.django-rest-framework.org/tutorial/5-relationships-and-hyperlinked-apis/ h ...
- Django REST framework 第五章 Relationships & Hyperlinked APIs
到目前为止,API内部的关系是使用主键来代表的.在这篇教程中,我们将提高API的凝聚力和可发现性,通过在相互关系上使用超链接. Creating an endpoint for the root of ...
- 5,基于关系和超链接的 API
Tutorial 5: Relationships & Hyperlinked APIs At the moment relationships within our API are repr ...
- django-rest-framework快速入门
前言:第一次接触django-rest-framework是在实习的时候.当时也不懂,看到视图用类方法写的感觉很牛逼的样子.因为官网是英文的,这对我的学习还是有一点的阻力的,所以当时也没怎么学.真是太 ...
- django rest framework 详解
Django REST framework 是用于构建Web API 的强大而灵活的工具包. 我们可能想使用REST框架的一些原因: Web浏览API对于开发人员来说是一个巨大的可用性. 认证策略包括 ...
- drf 教程
1, 序列化 Serialization 创建一个新环境 在做其他事之前,我们会用virtualenv创建一个新的虚拟环境.这将确保我们的包配置与我们正在工作的其他项目完全隔离. virtualenv ...
- Hibernate quick start
Preface Working with both Object-Oriented software and Relational Databases can be cumbersome and ti ...
- Apache Atlas
atlas英 [ˈætləs] 阿特拉斯. 美 [ˈætləs] n.地图集;〈比喻〉身负重担的人 == Apache Atlas Version: 1.1.0 Last Published: 201 ...
- django restframework 简单总结
官方文档:http://www.django-rest-framework.org/ model.py class Snippet(models.Model): created = models.Da ...
随机推荐
- 批量后台执行fio性能测试脚本
安装ansible工具: )直接yum install -y ansible; )然后更改配置,/etc/ansible/ansible.cfg,将里面的host_key_checking = Fal ...
- BZOJ4888 Tjoi2017异或和(树状数组)
化为前缀和相减.考虑每一位的贡献.则需要快速查询之前有几个数和当前数的差在第k位上为1.显然其与更高位是无关的.于是用BIT维护后k位的数的出现次数,瞎算一算即可. // luogu-judger-e ...
- C++解析(10):struct和class的区别
0.目录 1.默认访问级别 2.默认继承方式 2.1 分别独立继承 2.2 struct继承class 2.3 class继承struct 3.小结 1.默认访问级别 在用struct定义类时,所有成 ...
- py2exe使用总结
假如你用python写了个小程序,想给别人用或者给别人演示,但他电脑里没装python.wxpython等,这时候你可以试试py2exe,它是一个将python脚本转换成windows上的可执行程序( ...
- 【JavaScript】简介、<Script>标签及基本概念
一.前言 时光荏苒,岁月匆匆.今年年初进入数据平台部门转型做Web平台.要想搞好前端肯定要学好JavaScript,于是准备抓上一俩本书从基础学起. 二.内容 简介 JavaScript是 ...
- Linux内核设计与实现第六周读书笔记
第三章 进程管理 3.1 进程 进程是处于执行期的代码.通常进程还要包含其他资源,像打开的文件.挂起的信号.内核的内部数据.处理器状态.一个或多个具有内存映射的内存地址空间及一个或多个执行线程,当然还 ...
- Codeforces Round #353 (Div. 2) A
弱到只会写div2的A题... 题面: A. Infinite Sequence time limit per test 1 second memory limit per test 256 mega ...
- 代码收藏系列--javascript--移动端技巧
JS判断是否是手机端访问: var is_mobi = navigator.userAgent.toLowerCase().match(/(ipod|iphone|android|coolpad|mm ...
- PID控制算法的C语言实现四 增量型PID的C语言实现
/*------------------------------------------- 2 位置型PID C实现(控制电机转速) --------------------------------- ...
- spoj694 DISUBSTR - Distinct Substrings
Given a string, we need to find the total number of its distinct substrings. Input T- number of test ...