DRF使用超链接API实现真正RESTful
很多API并不是真正的实现了RESTful,而应该叫做RPC (Remote Procedure Call 远程过程调用),Roy Fielding曾经提到了它们的区别,原文如下:
I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.
What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?
— Roy Fielding
https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
大概意思是,如果应用状态引擎(API)不是超文本驱动的,那么就不是RESTful。
我的理解是,像超文本一样携带一个地址,可以寻址定位信息,如超文本的link属性。
超链接(Hypermedia)API
Hypermedia指的是,返回结果中提供链接,连向其他API方法,使得用户不查文档,也知道下一步应该做什么。比如,当用户向api.example.com的根目录发出请求,会得到这样一个文档:
{"link": {
"rel": "collection https://www.example.com/zoos",
"href": "https://api.example.com/zoos",
"title": "List of zoos",
"type": "application/vnd.yourformat+json"
}}
上面代码表示,文档中有一个link属性,用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系(collection关系,并给出该collection的网址),href表示API的路径,title表示API的标题,type表示返回类型。
创建api_root的Endpoint
回到教程的例子。在前面我们已经为snippets
和users
创建了Endpoint,现在来创建根目录的Endpoint,编辑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)
})
reverse()
函数用来返回snippets/urls.py
中viewname对应的url,如path('users/', views.UserList.as_view(), name='user-list')
。
然后添加到snippets/urls.py
中:
path('', views.api_root),
创建SnippetHighlight的Endpoint
还记得在上篇文章中提到的Snippet.highlighted
字段么:
我们现在为它创建Endpoint,继续编辑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)
然后添加到snippets/urls.py
中:
path('snippets/<int:pk>/highlight/', views.SnippetHighlight.as_view()),
因为
snippet.highlighted
不是JSON而是HTML,所以用[renderers.StaticHTMLRenderer]
返回预渲染的(pre-rendered)HTML。
HyperlinkedModelSerializer
在Web API设计中,一般有以下几种方式来表示实体之间的关系:
- 主键
- 超链接
- 关系实体(the related entity),唯一标识符字段(a unique identifying slug field)
- 关系实体,默认字符串(the default string representation)
- 关系实体,嵌入到父类中(the parent representation)
- 其他自定义
前2个比较熟悉,后面几个有点不太懂,我理解是类似于数据库的关联关系表。
DRF支持以上所有方式,这里我们用DRF的HyperlinkedModelSerializer
来实现真正的RESTful。在snippets/serializers.py
中把我们之前的代码:
class SnippetSerializer(serializers.ModelSerializer):
owner = serializers.ReadOnlyField(source='owner.username')
class Meta:
model = Snippet
fields = ['id', 'title', 'code', 'linenos', 'language', 'style', 'owner']
class UserSerializer(serializers.ModelSerializer):
snippets = serializers.PrimaryKeyRelatedField(many=True, queryset=Snippet.objects.all())
class Meta:
model = User
fields = ['id', 'username', 'snippets']
修改为:
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']
其中ModelSerializer
换成了HyperlinkedModelSerializer
,后者的区别如下:
默认不包含
id
字段包含
url
字段,用HyperlinkedIdentityField
表示源码:
serializer_url_field = HyperlinkedIdentityField
关系用
HyperlinkedRelatedField
表示,而不是PrimaryKeyRelatedField
源码:
serializer_related_field = HyperlinkedRelatedField
由于用了HyperlinkedModelSerializer,SnippetSerializer和UserSerializer的url字段默认指向的是'{model_name}-detail'
url pattern,这是DRF定义的,在示例中就是'snippet-detail'
和'user-detail'
。新增的highlight
字段和url
字段是一样的类型,它指向的是'snippet-highlight'
,而不是'snippet-detail'
。
修改url pattern
既然已经提到了url pattern,那么在snippets/urls.py
中修改一下:
from django.urls import path
from rest_framework.urlpatterns import format_suffix_patterns
from snippets import views
# API endpoints
urlpatterns = format_suffix_patterns([
path('', views.api_root),
path('snippets/', views.SnippetList.as_view(), name='snippet-list'),
path('snippets/<int:pk>/', views.SnippetDetail.as_view(), name='snippet-detail'),
path('snippets/<int:pk>/highlight/', views.SnippetHighlight.as_view(), name='snippet-highlight'),
path('users/', views.UserList.as_view(), name='user-list'),
path('users/<int:pk>/', views.UserDetail.as_view(), name='user-detail')
])
name就是在
serializers.py
和views.py
中用到的。
添加分页
REST设计基本原则提到了:处理好分页。DRF添加分页的方式很简单,编辑tutorial/settings.py
文件:
REST_FRAMEWORK = {
'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
'PAGE_SIZE': 10
}
东方说
我之前是在学SpringBoot的时候了解过RESTful API的超链接API,文章开头的那一段介绍就是当时写的笔记,DRF提供了HyperlinkedModelSerializer
来实现,还是比较好理解的,其中的细节需要在实战中再多多熟悉。
参考资料:
https://www.django-rest-framework.org/tutorial/5-relationships-and-hyperlinked-apis/
DRF使用超链接API实现真正RESTful的更多相关文章
- 在ASP.NET Core Web API中为RESTful服务增加对HAL的支持
HAL(Hypertext Application Language,超文本应用语言)是一种RESTful API的数据格式风格,为RESTful API的设计提供了接口规范,同时也降低了客户端与服务 ...
- Web API 入门系列 - RESTful API 设计指南
参考:https://developer.github.com/v3/ https://github.com/bolasblack/http-api-guide HTTP 协议 目前使用HTTP1. ...
- API认证&SDK&RESTful
python API的安全认证 我们根据pid加客户端的时间戳进行加密md5(pid|时间戳)得到的单向加密串,与时间戳,或者其它字段的串的url给服务端. 服务端接收到请求的url进行分析 客户 ...
- Web Api:基于RESTful标准
参考链接:http://www.cnblogs.com/lori/p/3555737.html 简单的了解到RESTful架构后,跟着以上链接做了一个小练习. Step1: 新建WebApi项目,新建 ...
- 【API设计】RESTful API 设计指南
RESTful API URL定位资源,用HTTP动词(GET,POST,DELETE,DETC)描述操作. 例如 . REST描述的是在网络中client和server的一种交互形式:REST本身不 ...
- 我是如何根据豆瓣api来理解Restful API设计的
1.什么是REST REST全称是Representational State Transfer,表述状态转移的意思.它是在Roy Fielding博士论文首次提出.REST本身没有创造新的技术.组件 ...
- 初识web API接口及Restful接口规范
一.web API接口 什么是web API接口?: 明确了请求方式,提供对应后台所需参数,请求url链接可以得到后台的响应数据 url : 返回数据的url https://api.map.baid ...
- 【Python之路】特别篇--服务商API认证、Restful、一致性哈希
API加密方式 1/ 加密方式: Md5 (随机字符串 + 时间戳) 2/ 发送方式: http://127.0.0.1:8888/index?pid= MD5加密值 | 时间戳 | 序号 服务端接收 ...
- 百度API车牌识别——Restful方式
源码下载地址:https://download.csdn.net/download/redhat588/11798294 Delphi xe 10.3.2 for windows 7 环境编译通过! ...
随机推荐
- 利用perspective 和 transform 里面的几个参数来实现旋转照片墙
旋转照片墙 首先,来看下,是什么效果吧,上效果图 ↓ 其实这个东西,很容易制作,先说下思路, 把照片都给叠在一起,然后 rotateY 旋转,给每张图片 旋转不一样的角度能构成一圈, 然后transl ...
- springboot打jar包将引用的第三方包、配置文件(.properties、.xml)、静态资源打在包外
1.外置配置文件 Springboot读取核心配置文件(.properties)的外部配置文件调用方式为 jar包当前目录下的/config目录 因此要外置配置文件就在jar所在目录新建config文 ...
- webgl智慧楼宇发光效果算法系列之高斯模糊
webgl智慧楼宇发光效果算法系列之高斯模糊 如果使用过PS之类的图像处理软件,相信对于模糊滤镜不会陌生,图像处理软件提供了众多的模糊算法.高斯模糊是其中的一种. 在我们的智慧楼宇的项目中,要求对楼宇 ...
- MySQL——事务ACID&隔离级别
数据库事务ACID&隔离级别 什么是事务 事务是用户定义的一个数据库操作序列.这些操作要么全执行,要么全不执行,是一个不可分割的工作单元.在关系型数据库中,事务可以是一条SQL语句,也可以是一 ...
- Jmeter介绍、下载及配置
Jmeter介绍: Apache JMeter是Apache组织开发的基于Java的压力测试工具.最初被设计用于Web应用测试,后来扩展到其他测试领域. 它可以用于测试静态和动态资源,例如静态文件.J ...
- pthread 互斥量
参考文献: [1] https://computing.llnl.gov/tutorials/pthreads/ 温故知新 在 OS 中,每个进程都独立地拥有: Process ID, process ...
- day1(初始化项目结构)
1.初始化项目结构 └─shiyanlou_project │ .gitignore │ README.en.md # 英文 │ README.md ...
- 第十八章、QListView/Model开发
老猿Python博文目录 专栏:使用PyQt开发图形界面Python应用 老猿Python博客地址 一.概述 QListView理论上可以和所有QAbstractItemModel派生的类如QStri ...
- PyQt(Python+Qt)学习随笔:部件的大小策略sizePolicy的含义
在Qt Designer中的每个部件,除了设置部件的位置(geometry)之外,还可以指定部件的大小策略sizePolicy.部件的sizePolicy用于说明部件在布局管理中的缩放方式,当部件没有 ...
- 深入理解python
1 python自身的威力 1.1 使用type.str.dir.其他内置函数 //type函数:返回任意对象的数据类型.比如:整型.字符串.列表.字典.元组.函数.类.模块,甚至类型对象都可以作为参 ...