Flask (五) RESTful API

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架构

每一个URI代表一种资源
客户端和服务器之间，传递这种资源的某种表现层
客户端通过四个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}