一、RESTful API设计

• 参考

天气1：https://www.sojson.com/open/api/weather/json.shtml?city=北京
天气2：http://t.weather.com/api/weather/cuty/101030100
豆瓣电影：http://api.douban.com/v2/movie/in_theaters

• 协议

网路传输协议
    HTTP
    HTTP:HTTO + SSL

• 域名

www.douban.com

API专有域名：api.douban.com
放到主域名下：www.douban.com/api/

• 版本

api.douban.com/v2
www.douban.com/api/v3/

• 路径

每一个URL对应就是一个资源，对资源的操作，不能用动词，只能用名词；

• HTTP动词

GET 获取资源、
POST 创建或更新资源
PUT 更新资源
DELETE 删除资源
HEAD 获取资源的元信息
OPTIONS 获取信息(能在客户端改变的)

• 过滤

?page=2&per=5
?limit=3
?sort=price

• 状态码

2xx 成功类
3xx 重定向
4xx 客户端错误
5xx 服务器错误

200 获取数据成功
201 创建或更新数据成功

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 - [*] ：服务器内部发生错误

二、RESTful API设计(原生方式)

• 业务逻辑

- 获取 用户 信息 成功
    - 将 用户数据 存入数据库 成功
        返回：用户注册成
    - 将 用户数据 存入数据库 失败
        返回：用户名已被注册

- 获取 用户 信息 失败
    返回：用户数据有问题(用户名、密码不能为空)

三、flask-restful

• 概述

快速构建REST API的支持。

• 官网

英文版: https://flask-restful.readthedocs.io/en/latest/
中文版: http://www.pythondoc.com/Flask-RESTful/

• 安装

pip install flask-restful

• 配置

api = Api()
api.init_app(app)

• 使用

# 定义资源
class Hello(Resource):
    def get(self):
        return {'msg':'hello world'}
        
# 添加资源
api.add_resource(Hello,'/',endpoint='hello')  # url_for有时候会用到endpoint
# 导入Hello时 注意位置 App.apis.类名

• 输入格式化定制

- 类型
    fields.String 字符串
    fields.Integer 整形
    fields.Nested  字典(级联数据)
    field.List  列表类型

- 格式定制
    onecat_fields = {
        'name': fields.String,
        'color': fields.String
    }

    resource_fields = { # 格式化定制
        'status': fields.Integer,
        'msg': fields.String,
        'date': fields.String,
        'data': fields.Nested(onecat_fields)
    }

- 通过装饰器方式进行输出格式化定制
    @marshal_with(resource_fields)
    def get(self):
        cat = Cat.query.first()
        print(type(cat))

        response_data = {
            'status': 200,
            'msg': '获取数据成功(使用Flaks-RESTful)',
            'date': str(time.ctime()),
            'data': cat
        }

- 注意
    如果返回输出数据，在定制格式中不存在，该数据会被过滤掉；
    如果返回输出数据，在定制格式中存在，正常显示；
    定制格式字段较多，返回输出数据字段不够，有默认值显示默认值(没有即显示null);