什么是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')
}
定义好的格式通过装饰器进行使用
class Users(Resource):
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}