很多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表示返回类型。

摘取自:http://www.ruanyifeng.com/blog/2014/05/restful_api.html

创建api_root的Endpoint

回到教程的例子。在前面我们已经为snippetsusers创建了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.pyviews.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/

https://spring.io/guides/tutorials/rest/

DRF使用超链接API实现真正RESTful的更多相关文章

  1. 在ASP.NET Core Web API中为RESTful服务增加对HAL的支持

    HAL(Hypertext Application Language,超文本应用语言)是一种RESTful API的数据格式风格,为RESTful API的设计提供了接口规范,同时也降低了客户端与服务 ...

  2. Web API 入门系列 - RESTful API 设计指南

    参考:https://developer.github.com/v3/  https://github.com/bolasblack/http-api-guide HTTP 协议 目前使用HTTP1. ...

  3. API认证&SDK&RESTful

    python API的安全认证   我们根据pid加客户端的时间戳进行加密md5(pid|时间戳)得到的单向加密串,与时间戳,或者其它字段的串的url给服务端. 服务端接收到请求的url进行分析 客户 ...

  4. Web Api:基于RESTful标准

    参考链接:http://www.cnblogs.com/lori/p/3555737.html 简单的了解到RESTful架构后,跟着以上链接做了一个小练习. Step1: 新建WebApi项目,新建 ...

  5. 【API设计】RESTful API 设计指南

    RESTful API URL定位资源,用HTTP动词(GET,POST,DELETE,DETC)描述操作. 例如 . REST描述的是在网络中client和server的一种交互形式:REST本身不 ...

  6. 我是如何根据豆瓣api来理解Restful API设计的

    1.什么是REST REST全称是Representational State Transfer,表述状态转移的意思.它是在Roy Fielding博士论文首次提出.REST本身没有创造新的技术.组件 ...

  7. 初识web API接口及Restful接口规范

    一.web API接口 什么是web API接口?: 明确了请求方式,提供对应后台所需参数,请求url链接可以得到后台的响应数据 url : 返回数据的url https://api.map.baid ...

  8. 【Python之路】特别篇--服务商API认证、Restful、一致性哈希

    API加密方式 1/ 加密方式: Md5 (随机字符串 + 时间戳) 2/ 发送方式: http://127.0.0.1:8888/index?pid= MD5加密值 | 时间戳 | 序号 服务端接收 ...

  9. 百度API车牌识别——Restful方式

    源码下载地址:https://download.csdn.net/download/redhat588/11798294 Delphi xe 10.3.2 for windows 7 环境编译通过! ...

随机推荐

  1. 看完这篇还不会 Elasticsearch 搜索,那我就哭了!

    本文主要介绍 ElasticSearch 搜索相关的知识,首先会介绍下 URI Search 和 Request Body Search,同时也会学习什么是搜索的相关性,如何衡量相关性. Search ...

  2. java数组作为函数返回值

    1 //将一个二维数组行和列元素互换.存到另一个二维数组 2 package test; 3 4 public class test1_8 { 5 public static int[][] huhu ...

  3. 使用github actions 完成一些自动化工作

    github actions 是什么? github actions是github的持续集成及自动化工作流服务,使用起来都比较方便.大部分github actions都可以在https://githu ...

  4. 不使用 MQ 如何实现 pub/sub 场景?

    hello,大家好,我是小黑,又和大家见面啦~~ 在配置中心中,有一个经典的 pub/sub 场景:某个配置项发生变更之后,需要实时的同步到各个服务端节点,同时推送给客户端集群. 在之前实现的简易版配 ...

  5. 在运行tsc编译.ts文件时,“因为在此系统上禁止运行脚本” 怎么解决?

    tsc : 无法加载文件 C:\Users\Administrator\AppData\Roaming\npm\tsc.ps1,因为在此系统上禁止运行脚本.有关详细信息,请参阅 https:/go.m ...

  6. bootstrap火速布局"企业级"页面

    套娃 .container(两边有margin)/container-fluid(无) 大盒,写一个当爹就行 .row 行 .col 列 列中可再嵌套行和列 大小 把屏幕分成十二列看 .col-(xs ...

  7. 软件工程与UML第三次作业

    博客班级 软件工程与UML2班 作业要求 本次作业要求 作业目标 <给至少5名同学提他的代码issue并用博客记录;根据收到的issue修改自己的代码> 作业源代码 我的码云仓库 学号 & ...

  8. 解决 spring-integration-mqtt 频繁报 Lost connection 错误

    问题描述 在之前的博客介绍了如何在 Spring Boot 集成 MQTT,后面使用中没有发现问题,最近发现一直报错: Lost connection: Connection lost; retryi ...

  9. MySQL——一致性非锁定读(快照读)&MVCC

    MySQL--一致性非锁定读(快照读) MySQL数据库中读分为一致性非锁定读.一致性锁定读 一致性非锁定读(快照读),普通的SELECT,通过多版本并发控制(MVCC)实现. 一致性锁定读(当前读) ...

  10. python批量definition query

    import arcpy mxd = arcpy.mapping.MapDocument("current") for lyr in arcpy.mapping.ListLayer ...