17-Django REST framework及RESTful简介

简介: 17-Django REST framework及RESTful简介

前言

  • 本篇开始学习Django REST framework

简介

  • Django REST framework可以帮助我们简化下面两部分的代码编写,大大提高REST API的开发速度
  1. 在序列化与反序列化时,虽然操作的数据不尽相同,但是执行的过程却是相似的,也就是说这部分代码是可以复用简化编写的。
  2. 在开发REST API的视图中,虽然每个视图具体操作的数据不同,但增、删、改、查的实现流程基本套路化,所以这部分代码也是可以复用简化编写的:
  • 增:校验请求数据 -> 执行反序列化过程 -> 保存数据库 -> 将保存的对象序列化并返回
  • 删:判断要删除的数据是否存在 -> 执行数据库删除
  • 改:判断要修改的数据是否存在 -> 校验请求的数据 -> 执行反序列化过程 -> 保存数据库 -> 将保存的对象序列化并返回
  • 查:查询数据库 -> 将数据序列化并返回

特点

  • Django REST framework 框架是一个用于构建Web API 的强大而又灵活的工具。
  • 通常简称为DRF框架 或 REST framework。
  • DRF框架是建立在Django框架基础之上,由Tom Christie大牛二次开发的开源项目
  • 提供了定义序列化器Serializer的方法,可以快速根据 Django ORM 或者其它库自动序列化/反序列化;
  • 提供了丰富的类视图、Mixin扩展类,简化视图的编写;
  • 丰富的定制层级:函数视图、类视图、视图集合到自动生成 API,满足各种需要;
  • 多种身份认证和权限认证方式的支持;
  • 内置了限流系统;
  • 直观的 API web 界面;
  • 可扩展性,插件丰富

认识RESTful

在前后端分离的应用模式里,后端API接口如何定义?

  • 对于接口的请求方式与路径,每个后端开发人员可能都有自己的定义方式,风格迥异。
  • 是否存在一种统一的定义方式,被广大开发人员接受认可的方式呢?
  • 这就是被普遍采用的API的RESTful设计风格。
  • 例如对于后端数据库中保存了商品的信息,前端可能需要对商品数据进行增删改查,那相应的每个操作后端都需要提供一个API接口:
    请求方法 请求地址 后端操作
请求方法 请求地址 后端操作
GET /goods 获取所有商品
POST /goods 增加商品
GET /goods/1 获取编号为1的商品
PUT /goods/1 修改编号为1的商品
DELETE /goods/1 删除编号为1的商品

说明:

  • RESTful是一种开发理念。REST是设计风格而不是标准。
  • 公司中的后端程序员在定义后端的接口时,可以选择是否遵守这种设计风格。
  • RESTful设计风格的API,每种请求方法,都对应后端一种数据库操作。

RESTful设计方法

1. 域名

  • 应该尽量将API部署在专用域名之下

https://api.example.com

  • 如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下

https://example.org/api/

2. 版本(Versioning)

  • 应该将API的版本号放入URL

http://www.example.com/app/1.0/foo

http://www.example.com/app/1.1/foo

http://www.example.com/app/2.0/foo

  • 另一种做法是,将版本号放在HTTP头信息中,但不如放入URL方便和直观。
  • 因为不同的版本,可以理解成同一种资源的不同表现形式,所以应该采用同一个URL。版本号可以在HTTP请求头信息的Accept字段中进行区分

Accept: vnd.example-com.foo+json; version=1.0

Accept: vnd.example-com.foo+json; version=1.1

Accept: vnd.example-com.foo+json; version=2.0

3. 路径(Endpoint)

路径又称"终点"(endpoint),表示API的具体网址,每个网址代表一种资源(resource)

  • (1) 资源作为网址,只能有名词,不能有动词,而且所用的名词往往与数据库的表名对应
  • 举例来说,以下是不好的例子:

/getProducts

/listOrders

/retreiveClientByOrder?orderId=1

对于一个简洁结构,你应该始终用名词。 此外,利用的HTTP方法可以分离网址中的资源名称的操作

GET /products :将返回所有产品清单

POST /products :将产品新建到集合

GET /products/4 :将获取产品 4

PATCH(或)PUT /products/4 :将更新产品 4

  • (2) API中的名词应该使用复数。无论子资源或者所有资源。
    举例来说,获取产品的API可以这样定义

获取单个产品:http://127.0.0.1:8080/AppName/rest/products/1

获取所有产品: http://127.0.0.1:8080/AppName/rest/products

4. HTTP动词

对于资源的具体操作类型,由HTTP动词表示。

常用的HTTP动词有下面四个(括号里是对应的SQL命令)。

GET(SELECT):从服务器取出资源(一项或多项)。

POST(CREATE):在服务器新建一个资源。

PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。

DELETE(DELETE):从服务器删除资源。

还有三个不常用的HTTP动词。

PATCH(UPDATE):在服务器更新(更新)资源(客户端提供改变的属性)。

HEAD:获取资源的元数据。

OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的。

下面是一些例子

GET /zoos:列出所有动物园

POST /zoos:新建一个动物园(上传文件)

GET /zoos/ID:获取某个指定动物园的信息

PUT /zoos/ID:更新某个指定动物园的信息(提供该动物园的全部信息)

PATCH /zoos/ID:更新某个指定动物园的信息(提供该动物园的部分信息)

DELETE /zoos/ID:删除某个动物园

GET /zoos/ID/animals:列出某个指定动物园的所有动物

DELETE /zoos/ID/animals/ID:删除某个指定动物园的指定动物

5. 过滤信息(Filtering)

如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果。

下面是一些常见的参数。

?limit=10:指定返回记录的数量

?offset=10:指定返回记录的开始位置。

?page=2&per_page=100:指定第几页,以及每页的记录数。

?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。

?animal_type_id=1:指定筛选条件

参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复。比如,GET /zoos/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

6. 状态码(Status Codes)

服务器向用户返回的状态码和提示信息,常见的有以下一些(方括号中是该状态码对应的HTTP动词)

  • 200 OK - [GET]:服务器成功返回用户请求的数据
  • 201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
    *202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
  • 204 NO CONTENT - [DELETE]:用户删除数据成功。
  • 400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作
  • 401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
  • 403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
  • 404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
  • 406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
  • 410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
  • 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
  • 500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功

7. 错误处理(Error handling)

如果状态码是4xx,服务器就应该向用户返回出错信息。一般来说,返回的信息中将error作为键名,出错信息作为键值即可。

{
    error: "Invalid API key"
}

8.返回结果

针对不同操作,服务器向用户返回的结果应该符合以下规范。

GET /collection:返回资源对象的列表(数组)

GET /collection/resource:返回单个资源对象

POST /collection:返回新生成的资源对象

PUT /collection/resource:返回完整的资源对象

PATCH /collection/resource:返回完整的资源对象

DELETE /collection/resource:返回一个空文档

9. 超媒体(Hypermedia API)

RESTful API最好做到Hypermedia(即返回结果中提供链接,连向其他API方法),使得用户不查文档,也知道下一步应该做什么。

比如,Github的API就是这种设计,访问api.github.com会得到一个所有可用API的网址列表。

{
"current_user_url": "https://api.github.com/user",
"authorizations_url": "https://api.github.com/authorizations",
// ...
}

从上面可以看到,如果想获取当前用户的信息,应该去访问api.github.com/user,然后就得到了下面结果。

{
  "message": "Requires authentication",
  "documentation_url": "https://developer.github.com/v3"
}

上面代码表示,服务器给出了提示信息,以及文档的网址。

10. 其他

  • 服务器返回的数据格式,应该尽量使用JSON,避免使用XML
相关文章
|
4月前
|
JSON API 数据安全/隐私保护
哇塞!Django REST framework 太逆天啦!构建 API 服务从未如此轻松,你还不来试试?
【8月更文挑战第31天】Django REST framework(DRF)是基于Django框架的高效Web API开发工具,提供序列化、视图集、路由等功能,简化API构建流程。使用DRF可轻松实现数据的序列化与反序列化,并支持权限管理和认证机制以保障API安全。安装DRF只需通过`pip install djangorestframework`命令。要创建基本项目,先安装Django并创建新应用,定义模型、序列化器及视图集,最后配置路由。测试API时,可通过Postman发送HTTP请求验证功能。无论项目大小,DRF均能提供强大支持。
49 0
|
4月前
|
中间件 API 网络架构
Django后端架构开发:从匿名用户API节流到REST自定义认证
Django后端架构开发:从匿名用户API节流到REST自定义认证
49 0
|
5月前
|
安全 API 网络安全
Django RESTful API安全实践
【7月更文挑战第19天】构建安全的Django RESTful API需要综合考虑多个方面,包括身份验证与授权、数据验证与清洗、安全的HTTPS连接、限制请求频率以及审计与日志记录等。通过实施这些安全实践,可以有效地保护API服务免受各种安全威胁的侵害,确保用户数据的安全性和服务的可用性。开发者在开发RESTful API时,应始终将安全性放在首位,确保API服务的安全可靠。
|
6月前
|
存储 JSON 数据库
Django REST framework关联序列化器详解:掌握复杂关系的序列化与反序列化艺术
Django REST framework关联序列化器详解:掌握复杂关系的序列化与反序列化艺术
|
6月前
|
安全 API 数据安全/隐私保护
Django REST framework安全实践:轻松实现认证、权限与限流功能
Django REST framework安全实践:轻松实现认证、权限与限流功能
|
6月前
|
JSON 搜索推荐 数据库
Django REST framework数据展示技巧:分页、过滤与搜索的实用配置与实践
Django REST framework数据展示技巧:分页、过滤与搜索的实用配置与实践
|
6月前
|
JSON API 网络架构
Django REST framework视图集与路由详解:深入理解ViewSet、ModelViewSet与路由映射器
Django REST framework视图集与路由详解:深入理解ViewSet、ModelViewSet与路由映射器
|
6月前
|
前端开发 数据管理 API
Django REST framework中GenericAPIView与混入扩展类详解
Django REST framework中GenericAPIView与混入扩展类详解
|
5月前
|
XML 缓存 API
REST原则、RESTful架构
REST原则、RESTful架构
63 0
|
29天前
|
JSON 缓存 JavaScript
深入浅出:使用Node.js构建RESTful API
在这个数字时代,API已成为软件开发的基石之一。本文旨在引导初学者通过Node.js和Express框架快速搭建一个功能完备的RESTful API。我们将从零开始,逐步深入,不仅涉及代码编写,还包括设计原则、最佳实践及调试技巧。无论你是初探后端开发,还是希望扩展你的技术栈,这篇文章都将是你的理想指南。