Flask (五) RESTful API

柴耀
2023-12-01

RESTful API


什么是REST

一种软件架构风格、设计风格、而不是标准,只是提供了一组设计原则和约束条件。它主要用户客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存机制等。

REST全称是Representational State Transfer,表征性状态转移。首次在2000年Roy Thomas Fielding的博士论文中出现,Fielding是一个非常重要的人,他是HTTP协议(1.0版和1.1版)的主要设计者,Apache服务器软件的作者之一,Apache基金会的第一任主席。所以,他的这篇论文一经发表,就引起了广泛的关注。

论文:

本文研究计算机科学两大前沿----软件和网络----的交叉点。长期以来,软件研究主要关注软件设计的分类、设计方法的演化,很少客观地评估不同的设计选择对系统行为的影响。而相反地,网络研究主要关注系统之间通信行为的细节、如何改进特定通信机制的表现,常常忽视了一个事实,那就是改变应用程序的互动风格比改变互动协议,对整体表现有更大的影响。我这篇文章的写作目的,就是想在符合架构原理的前提下,理解和评估以网络为基础的应用软件的架构设计,得到一个功能强、性能好、适宜通信的架构。

 

REST爆发

其实在REST架构推出的十几年间,它并没有一路高歌的发展,真正的大范围推广是在2013年之后,伴随着移动端的飞速发展,越来越多人的开始意识到,网站即软件,而且是一种新型的软件。

这种"互联网软件采用"客户端/服务器"模式,也就是我们常说的C/S模式,这一切建立在分布式体系上,通过互联网通信,具有高延时,高并发等特点。

网站开发,完全采用软件开发开发的模式。但传统上,软件和网络是两个不同的领域,很少有交集,软件开发主要针对单机环境,网络则主要研究系统之间的通信。我们需要考虑的是如何开发在互联网环境中使用软件。

 

理解RESTful

要理解RESTful架构,最好的就是去理解它的单词 Representational State Transfer 到底是什么意思,它的每一个词到底要表达什么。

REST的释义,"表现层状态转化",其实这省略了主语。“表现层”其实指的是“资源(Resource)”的“表现层”。

资源(Resource)

所谓“资源”,就是网络上的一个实体,或者说是网络上的一个具体信息。它可以是一段文本,一张图片,一首歌曲,一种服务,总之就是一个具体的实例。你可以使用一个URI(统一资源定位符)指向它,每种资源对应一个特定的URI。要获取这个资源,访问它的URI就可以了,因此URI就成了每一个资源的地址或独一无二的识别符。所谓“上网”就是与互联网上一系列的“资源”互动,调用它们的URI。

表现层(Representation)

“资源”是一种信息实体,它可以有多种外在表现形式。我们把“资源”具体呈现出来的形式,叫做它的”表现层“(Representation)。

URI只代表资源的实体,不代表它的形式。严格地说,有些网站最后的”.html“后缀名是不必要的,因为这个后缀表示格式,属于”表现层“范畴,而URI应该只代表”资源“的位置。它的具体表现形式,应该在HTTP请求头的信息中使用Accept和Content-Type字段指定。

状态转换(State Transfer)

访问一个网站,就代表客户端和服务端的一个互动过程。在这个过程中,势必涉及到数据和状态的变化。

互联网通信协议HTTP协议,是一个无状态协议。这意味着,所有的状态都保存在服务端。因此,如果客户端想要操作服务器,就必须通过某种手段,让服务器端发生”状态转换(State Transfer)“。而这种转换是建立在表现层之上的,所以就是”表现层状态转化“。

客户端用到的手段,只能是HTTP协议。具体来说,就是HTTP协议中,四个表示操作方式的动词:GET,POST,PUT,DELETE。它们分别对应四种基本操作:GET用来获取资源,POST用来新建资源(也可用于更新资源),PUT用来更新资源,DELETE用来删除资源

 

到底什么是RESTful架构

  1. 每一个URI代表一种资源

  2. 客户端和服务器之间,传递这种资源的某种表现层

  3. 客户端通过四个HTTP动词,对服务端资源进行操作,实现”表现层状态转换“

RESTful API设计

协议

API与用户的通信协议,通常使用HTTP(S)协议。

域名

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

http://api.hello.com
 

如果确定API很简单,不会有大规模扩充,可以考虑放在主域名之下。

http://www.hello.com/api/
 
版本

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

http://api.rock.com/v1/
 

也有做法是将版本号放在HTTP的头信息中,但不如放在URL中方便和直观。GITHUB是这么搞的。

路径(Endpoint)

路径又称”终点“(endpoint),表示API的具体网址。

在RESTful架构中,每个网址代表一种资源(Resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的”集合“(collection),所以API中的名词也应该使用复数。

HTTP动词

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

HTTP常用动词

  • GET(SELECT):从服务器取出资源

  • POST(CREATE or UPDATE):在服务器创建资源或更新资源

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

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

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

  • HEAD:获取资源的元数据

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

示例

  • GET /students:获取所有学生

  • POST /students:新建学生

  • GET /students/id:获取某一个学生

  • PUT /students/id :更新某个学生的信息(需要提供学生的全部信息)

  • PATCH /students/id:更新某个学生的信息(需要提供学生变更部分信息)

  • DELETE /students/id:删除某个学生

过滤信息(Filtering)

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

  • ?limit=10

  • ?offset=10

  • ?page=2&per_page=20

  • ?sortby=name&order=desc

  • ?student_id=id

参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复,比如 GET /students/id 和 ?student_id=id

状态码

服务器向用户返回的状态码和提示信息,常见的有以下一些地方

  • 200 OK - [GET]:服务器成功返回用户请求的数据

  • 201 CREATED -[POST/PUT/PATCH]:用户新建或修改数据成功

  • 202 Accepted - [*] :表示一个请求已经进入后台排队(异步任务)

  • 204 NO CONTENT - [DELETE]:表示数据删除成功

  • 400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误

  • 401 Unauthorized - [*] :表示用户没有权限(令牌,用户名,密码错误)

  • 403 Forbidden - [*]:表示用户得到授权,但是访问是被禁止的

  • 404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录

  • 406 Not Acceptable - [*]:用户请求格式不可得

  • 410 Gone - [GET] :用户请求的资源被永久移除,且不会再得到的

  • 422 Unprocesable entity -[POST/PUT/PATCH]:当创建一个对象时,发生一个验证错误

  • 500 INTERNAL SERVER EROR - [*] :服务器内部发生错误

错误处理

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

返回结果

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

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

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

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

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

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

  • DELETE /collection/id:返回一个空文档

使用链接关联资源

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

{
   "link": {
       "rel":   "collection https://www.hello.com/zoostudents",
       "href":  "https://api.hello.com/students",
       "title": "List of students",
       "type":  "application/vnd.yourformat+json"
     }
}
 
  • rel:表示这个API与当前网址的关系

  • href:表示API的路径

  • title:表示API的标题

  • type:表示返回的类型

其它
  • 服务器返回的数据格式,应该尽量使用JSON

  • API的身份认证应该使用OAuth2.0框架

 

Flask-RESTful

https://flask-restful.readthedocs.io/en/latest/

基本使用

  • 安装

# pip 安装
pip install flask-restful
# 源码安装
git clone https://github.com/flask-restful/flask-restful.git
python setup.py develop
 
  • 创建Resource实现类

class HelloRESTful(Resource):
   def get(self):
       return {"data":"Hello GET"}
   def post(self):
       return {'data':'hello POST'}
 
  • 创建API对象,并注册路由

# ① 创建并初始化
api = API(app)
# ② 创建,之后初始化
api = API()
api.init_app(app)
# 注册路由 
api.add_resource(HelloRESTFul,"/")

字段格式化

fields进行定义
marshal_with进行使用
    特性
       显示我们设计的数据结构
       默认返回的数据如果在预定义结构中不存在,数据会被自动过滤
       如果返回的数据在预定义的结构中存在,数据会正常返回
       如果返回的数据比预定义结构中的字段少,预定义的字段会呈现一个默认值
     
    定义字段输出
       使用字典进行定义
       常用都是基本类型: String, Integer
     
           # 格式化字段
           user_fields = {
               'msg': fields.String,
               'status': fields.Integer,
               'data': fields.String(attribute='private_data'),
               'default_data': fields.String(default='1')
           }
       定义好的格式通过装饰器进行使用
           @marshal_with(需要返回的数据格式),  return返回字典就ok了
               class Users(Resource):
                   @marshal_with(user_fields)
                   def get(self):
                       return {'msg':'呵呵', 'data':'没有数据', 'age':'22', 'private_data':'表中数据'}
    级联数据: 嵌套字典
        Nested
     
           # 格式化字段
           usermodel_fileds = {
               'id': fields.Integer,
               'name': fields.String,
           }
           user2_fields = {
               'msg': fields.String(default='ok'),
               'status': fields.Integer(default=1),
               'data': fields.Nested(usermodel_fileds)
           }
     
    结构允许嵌套列表
        fields.List(fields.Nested) 
     
           # 格式化字段
           usermodel_fileds = {
               'id': fields.Integer,
               'name': fields.String,
           }
           users3_fields = {
               'status': fields.String(default=1),
               'msg': fields.String,
               'data': fields.List(fields.Nested(usermodel_fileds))
           }
 

 

URL

连接字段
   就是将当前数据的操作api暴露出来
   根据提供的url和唯一标识进行数据操作
# 格式化字段
usermodel_fileds = {
   'id': fields.Integer,
   'name': fields.String,
   'url': fields.Url('id', absolute=True)
}
# 在add_resource中提供对应的endpoint
api.add_resource(Users4, '/user4/', endpoint='id')
 

 

参数解析

可以不通过request.form或request.args获取参数, 而是通过reqparse.RequestParser来解析
   # 参数转换器
   parser = reqparse.RequestParser()
   parser.add_argument('name', type=str, action='append') # 支持多个name
   parser.add_argument('id', type=int, required=True, help='id是必须的') # 必需参数
   parser.add_argument('fldt_active', type=str, location='cookies') # 获取cookies中的数据
   class Users4(Resource):
       def get(self):
           parse = parser.parse_args()
           user_name = parse.get('name')
           id = parse.get('id')
           fldt_active = parse.get('fldt_active')
           return {'name': user_name, 'id': id, 'fldt_active':fldt_active}
 
 

 

 

转载于:https://www.cnblogs.com/gugubeng/p/9722818.html

 类似资料: