用 Flask 来写个轻博客 (35) — 使用 Flask-RESTful 来构建 RESTful API 之四

Blog 项目源码：https://github.com/JmilkFan/JmilkFan-s-Blog

目录

• 目录
• 前文列表
• POST 请求
• 身份认证
• 测试

前文列表

用 Flask 来写个轻博客 (1) — 创建项目

用 Flask 来写个轻博客 (2) — Hello World！

用 Flask 来写个轻博客 (3) — (M)VC_连接 MySQL 和 SQLAlchemy

用 Flask 来写个轻博客 (4) — (M)VC_创建数据模型和表

用 Flask 来写个轻博客 (5) — (M)VC_SQLAlchemy 的 CRUD 详解

用 Flask 来写个轻博客 (6) — (M)VC_models 的关系(one to many)

用 Flask 来写个轻博客 (7) — (M)VC_models 的关系(many to many)

用 Flask 来写个轻博客 (8) — (M)VC_Alembic 管理数据库结构的升级和降级

用 Flask 来写个轻博客 (9) — M(V)C_Jinja 语法基础快速概览

用 Flask 来写个轻博客 (10) — M(V)C_Jinja 常用过滤器与 Flask 特殊变量及方法

用 Flask 来写个轻博客 (11) — M(V)C_创建视图函数

用 Flask 来写个轻博客 (12) — M(V)C_编写和继承 Jinja 模板

用 Flask 来写个轻博客 (13) — M(V)C_WTForms 服务端表单检验

用 Flask 来写个轻博客 (14) — M(V)C_实现项目首页的模板

用 Flask 来写个轻博客 (15) — M(V)C_实现博文页面评论表单

用 Flask 来写个轻博客 (16) — MV(C)_Flask Blueprint 蓝图

用 Flask 来写个轻博客 (17) — MV(C)_应用蓝图来重构项目

用 Flask 来写个轻博客 (18) — 使用工厂模式来生成应用对象

用 Flask 来写个轻博客 (19) — 以 Bcrypt 密文存储账户信息与实现用户登陆表单

用 Flask 来写个轻博客 (20) — 实现注册表单与应用 reCAPTCHA 来实现验证码

用 Flask 来写个轻博客 (21) — 结合 reCAPTCHA 验证码实现用户注册与登录

用 Flask 来写个轻博客 (22) — 实现博客文章的添加和编辑页面

用 Flask 来写个轻博客 (23) — 应用 OAuth 来实现 Facebook 第三方登录

用 Flask 来写个轻博客 (24) — 使用 Flask-Login 来保护应用安全

用 Flask 来写个轻博客 (25) — 使用 Flask-Principal 实现角色权限功能

用 Flask 来写个轻博客 (26) — 使用 Flask-Celery-Helper 实现异步任务

用 Flask 来写个轻博客 (27) — 使用 Flask-Cache 实现网页缓存加速

用 Flask 来写个轻博客 (29) — 使用 Flask-Admin 实现后台管理 SQLAlchemy

用 Flask 来写个轻博客 (30) — 使用 Flask-Admin 增强文章管理功能

用 Flask 来写个轻博客 (31) — 使用 Flask-Admin 实现 FileSystem 管理

用 Flask 来写个轻博客 (32) — 使用 Flask-RESTful 来构建 RESTful API 之一

用 Flask 来写个轻博客 (33) — 使用 Flask-RESTful 来构建 RESTful API 之二

用 Flask 来写个轻博客 (34) — 使用 Flask-RESTful 来构建 RESTful API 之三

POST 请求

前三篇博文介绍了如果实现 GET 请求, 接下来继续实现 POST 创建数据请求.

• 执行 Create 操作, 就肯定少不了要向服务端传入数据. 所以第一步当然就是定义解析器了.
  
  vim jmilkfansblog/controllers/flask_restful/parsers.py

from flask.ext.restful import reqparse

post_post_parser = reqparse.RequestParser()

post_post_parser.add_argument(
    'title',
    type=str,
    required=True,
    help='Title is required!')

post_post_parser.add_argument(
    'text',
    type=str,
    required=True,
    help='Text is required!')

post_post_parser.add_argument(
    'tags',
    type=str,
    action='append')

post_post_parser.add_argument(
    'token',
    type=str,
    required=True,
    help='Auth Token is required to create posts.')

NOTE 1: add_argument 的关键字参数 action='append' 指定了传入的参数会转换为以字典为元素的列表数据类型. 这是为了便于创建 post.tags 对象.

NOTE 2: 定义 token 参数是为了后期的身份认证做准备

• 在资源来 PostApi 中实现 post()方法
  
  vim jmilkfansblog/controllers/flask_restful/posts.py

class PostApi(Resource):
    """Restful API of posts resource."""
    ...
        def post(self, post_id=None):
        """Can be execute when receive HTTP Method `POST`.
        """

        if post_id:
            abort(400)
        else:
            args = parsers.post_post_parser.parse_args(strict=True)

            new_post = Post()
            new_post.title = args['title']
            new_post.date = datetime.datetime.now()
            new_post.text = args['text']
            new_post.user = user

            if args['tags']:
                for item in args['tags']:
                    tag = Tag.query.filter_by(name=item).first()
                    # If the tag already exist, append.
                    if tag:
                        new_post.tags.append(tag)
                    # If the tag not exist, create the new one.
                    # Will be write into DB with session do.
                    else:
                        new_tag = Tag()
                        new_tag.name = item
                        new_post.tags.append(new_tag)
        db.session.add(new_post)
        db.session.commit()
        return (new_post.id, 201)

NOTE 1: post() 返回了一个 Tuple 类型对象, 第二个元素会作为 Response Hander 中的 HTTP status_int 状态码.

身份认证

需要注意的是, 对外开发的 RESTful API 一定要非常注重安全, 所有从外部对数据库的写入操作请求都必须进行身份认证.

身份认证的功能我们仍然可以由 Flask-Login 来支持, 但很明显的, 这并不符合 REST 的无状态约束. 所以我们在这里引入 Token 的概念, 外部请求如果希望通过 RESTful API 执行写数据库操作时, 必须携带用户登录信息, 通过身份认证之后, 再由服务端发放一段时间内有效的 Token. 身份认证在整个项目中也应当作为一种资源来定义.

• 首先还是定义 auth 解析器来接受用户信息
  
  vim jmilkfansblog/controllers/flask_restful/parsers.py

########################################################
# User's HTTP Request Parser
########################################################

user_post_parser = reqparse.RequestParser()

user_post_parser.add_argument(
    'username',
    type=str,
    required=True,
    help='Username is required!')

user_post_parser.add_argument(
    'password',
    type=str,
    required=True,
    help='Password is required!')

NOTE : auth 的解析器只需要用户名和密码两个参数.

• 创建认证资源 auth 的资源类
  
  vim jmilkfansblog/controllers/flask_restful/auth.py

from itsdangerous import TimedJSONWebSignatureSerializer as Serializer

from flask import abort, current_app
from flask.ext.restful import Resource

from jmilkfansblog.controllers.flask_restful import parsers
from jmilkfansblog.db.sqlalchemy.models import User

class AuthApi(Resource):
    """Restful api of Auth."""

    def post(self):
        """Can be execute when receive HTTP Method `POST`."""

        args = parsers.user_post_parser.parse_args()
        user = User.query.filter_by(username=args['username']).first()

        # Check the args['password'] whether as same as user.password.
        if user.check_password(args['password']):
            # serializer object will be saved the token period of time.
            serializer = Serializer(
                current_app.config['SECRET_KEY'],
                expires_in=600)
            return {'token': serializer.dumps({'id': user.id})}
        else:
            abort(401)

NOTE 1: Token 使用 Python 内建的 itsdangerous 库来实现, itsdangerous.TimedJSONWebSignatureSerializer() 的第一个参数需要传入 app 对象的私钥, 该私钥在之前的 Flask-WTForm 已经定义在 config.py 中了. 第二个参数定义了 Token 的有效时间.

NOTE 2: 我们使用 post() 方法来实现用户身份验证和发放 Token

• 定义资源 auth 的路由
  
  vim jmilkfansblog/__init__.py

def create_app(object_name):
    ...
    restful_api.add_resource(
        AuthApi,
        '/api/auth',
        endpoint='restful_api_auth')
    restful_api.init_app(app)

• 为 User 对象实现 Token 验证方法
  
  需要注意的是: 这个 Token 应该是有时限的, 如果永久生效则会非常危险. 所以我们还需要对有时限的 Token 进行校验, 确定其没有失效.
  
  vim jmilkfansblog/models.py

...

class User(db.Model):
    """Represents Proected users."""
    ...
    @staticmethod
    @cache.memoize(60)
    def verify_auth_token(token):
        """Validate the token whether is night."""

        serializer = Serializer(
            current_app.config['SECRET_KEY'])
        try:
            # serializer object already has tokens in itself and wait for
            # compare with token from HTTP Request /api/posts Method `POST`.
            data = serializer.loads(token)
        except SignatureExpired:
            return None
        except BadSignature:
            return None

        user = User.query.filter_by(id=data['id']).first()
        return user

NOTE: 使用 itsdangerous.TimedJSONWebSignatureSerializer.loads() 来进行 Token 验证, 如果验证失败的话, 我们直接返回 None

• 现在我们拥有了生成 Token 和验证 Token 的支撑, 最后我们在 PostApi.post() 中加入 Token 验证机制.

  vim jmilkfansblog/controllers/flask_restful/posts.py

    def post(self, post_id=None):
        """Can be execute when receive HTTP Method `POST`.
        """

        if post_id:
            abort(400)
        else:
            args = parsers.post_post_parser.parse_args(strict=True)

            # Validate the user identity via token(/api/auth POST).
            # Will be create the post(/api/posts POST), if pass with validate token.
            user = User.verify_auth_token(args['token'])
            if not user:
                abort(401)
        ...

测试

• 不加 Token 的 POST 请求

(env) jmilkfan@JmilkFan-Devstack:/opt/JmilkFan-s-Blog$ curl -d "title=Just Test POST" -d "text=Hello world" -d "tags=Python" http://localhost:8089/api/posts
{
    "message": {
        "token": "Auth Token is required to create posts."
    }
}

• 创建 Token

(env) jmilkfan@JmilkFan-Devstack:/opt/JmilkFan-s-Blog$ curl -d "username=<username>" -d "password=<password>" http://localhost:8089/api/auth{
    "token": "eyJhbGciOiJIUzI1NiIsImV4cCI6MTQ4MzM1MjkwNSwiaWF0IjoxNDgzMzUyMzA1fQ.eyJpZCI6IjY1Y2I5NzkyLWI4NzYtNDllNy1iMmM1LTQ2NDY4NjI0MTk5ZSJ9.hYpczUEZUalgzutyyIViheBd_jnnCmegvp4sazHIEoA"
}

• 加 Token 的 POST 请求

(env) jmilkfan@JmilkFan-Devstack:/opt/JmilkFan-s-Blog$ curl -d "title=Just Test" -d "text=Hello" -d "tags=Python" -d "token=eyJhbGciOiJIUzI1NiIsImV4cCI6MTQ4MzM1MjkwNSwiaWF0IjoxNDgzMzUyMzA1fQ.eyJpZCI6IjY1Y2I5NzkyLWI4NzYtNDllNy1iMmM1LTQ2NDY4NjI0MTk5ZSJ9.hYpczUEZUalgzutyyIViheBd_jnnCmegvp4sazHIEoA" http://localhost:8089/api/posts
"1746b650-bcab-436b-82ab-7411e252b576"

数据库记录 :

mysql> select * from posts;
+--------------------------------------+-----------+-----------------+---------------------+--------------------------------------+
| id                                   | title     | text            | publish_date        | user_id                              |
+--------------------------------------+-----------+-----------------+---------------------+--------------------------------------+
| 1746b650-bcab-436b-82ab-7411e252b576 | Just Test | Hello           | NULL                | 65cb9792-b876-49e7-b2c5-46468624199e |
| 1af8f334-c9ac-4eba-bdca-4dda597aba70 | 333333333 | <p>22222</p>
  | 2016-12-17 22:39:16 | 65cb9792-b876-49e7-b2c5-46468624199e |
| 29bab6a0-6a0f-48f1-a088-6c271cebe906 | 222222    | <p>222222</p>
 | 2016-12-27 22:35:00 | 65cb9792-b876-49e7-b2c5-46468624199e |
| 9c25d00e-49a7-4369-ac83-c0aca046ba73 | Just Test | Hello           | NULL                | 65cb9792-b876-49e7-b2c5-46468624199e |
+--------------------------------------+-----------+-----------------+---------------------+--------------------------------------+