原创译文，如需转载，请联系译者。
我的简书博客:nummy

原文地址:Implementing a RESTful Web API with Python & Flask

简介

首先，安装Flask

pip install flask

阅读这篇文章之前我假设你已经了解RESTful API的相关概念，如果不清楚，可以阅读我之前写的这篇博客[Designing a RESTful Web API.](http://blog.luisrei.com/articles/rest.html)

Flask是一个使用Python开发的基于Werkzeug的Web框架。
Flask非常适合于开发RESTful API，因为它具有以下特点：

• 使用Python进行开发，Python简洁易懂

• 容易上手

• 灵活

• 可以部署到不同的环境

• 支持RESTful请求分发

我一般是用curl命令进行测试，除此之外，还可以使用Chrome浏览器的postman扩展。

资源

首先，我创建一个完整的应用，支持响应/, /articles以及/article/:id。

from flask import Flask, url_for
app = Flask(__name__)

@app.route(\'/\')
def api_root():
    return \'Welcome\'

@app.route(\'/articles\')
def api_articles():
    return \'List of \' + url_for(\'api_articles\')

@app.route(\'/articles/\')
def api_article(articleid):
    return \'You are reading \' + articleid

if __name__ == \'__main__\':
    app.run()

可以使用curl命令发送请求：

curl http://127.0.0.1:5000/

响应结果分别如下所示：

GET /
Welcome

GET /articles
List of /articles

GET /articles/123
You are reading 123

路由中还可以使用类型定义:

@app.route(\'/articles/\')

上面的路由可以替换成下面的例子：

@app.route(\'/articles/\')
@app.route(\'/articles/\')
@app.route(\'/articles/\')

默认的类型为字符串。

请求

请求参数

假设需要响应一个/hello请求，使用get方法，并传递参数name

from flask import request

@app.route(\'/hello\')
def api_hello():
    if \'name\' in request.args:
        return \'Hello \' + request.args[\'name\']
    else:
        return \'Hello John Doe\'

服务器会返回如下响应信息：

GET /hello
Hello John Doe

GET /hello?name=Luis
Hello Luis

请求方法

Flask支持不同的请求方法：

@app.route(\'/echo\', methods = [\'GET\', \'POST\', \'PATCH\', \'PUT\', \'DELETE\'])
def api_echo():
    if request.method == \'GET\':
        return \"ECHO: GET\\n\"

    elif request.method == \'POST\':
        return \"ECHO: POST\\n\"

    elif request.method == \'PATCH\':
        return \"ECHO: PACTH\\n\"

    elif request.method == \'PUT\':
        return \"ECHO: PUT\\n\"

    elif request.method == \'DELETE\':
        return \"ECHO: DELETE\"

可以使用如下命令进行测试:

curl -X PATCH http://127.0.0.1:5000/echo

不同请求方法的响应如下：

GET /echo
ECHO: GET

POST /ECHO
ECHO: POST
...

请求数据和请求头

通常使用POST方法和PATCH方法的时候，都会发送附加的数据，这些数据的格式可能如下：普通文本(plain text)， JSON，XML，二进制文件或者用户自定义格式。
Flask中使用request.headers类字典对象来获取请求头信息，使用request.data 获取请求数据，如果发送类型是application/json，则可以使用request.get_json()来获取JSON数据。

from flask import json

@app.route(\'/messages\', methods = [\'POST\'])
def api_message():

    if request.headers[\'Content-Type\'] == \'text/plain\':
        return \"Text Message: \" + request.data

    elif request.headers[\'Content-Type\'] == \'application/json\':
        return \"JSON Message: \" + json.dumps(request.json)

    elif request.headers[\'Content-Type\'] == \'application/octet-stream\':
        f = open(\'./binary\', \'wb\')
        f.write(request.data)
                f.close()
        return \"Binary message written!\"

    else:
        return \"415 Unsupported Media Type ;)\"

使用如下命令指定请求数据类型进行测试：

curl -H \"Content-type: application/json\" \\
-X POST http://127.0.0.1:5000/messages -d \'{\"message\":\"Hello Data\"}\'

使用下面的curl命令来发送一个文件:

curl -H \"Content-type: application/octet-stream\" \\
-X POST http://127.0.0.1:5000/messages --data-binary @message.bin

不同数据类型的响应结果如下所示：

POST /messages {\"message\": \"Hello Data\"}
Content-type: application/json
JSON Message: {\"message\": \"Hello Data\"}

POST /message 
Content-type: application/octet-stream
Binary message written!

注意Flask可以通过request.files获取上传的文件，curl可以使用-F选项模拟上传文件的过程。

响应

Flask使用Response类处理响应。

from flask import Response

@app.route(\'/hello\', methods = [\'GET\'])
def api_hello():
    data = {
        \'hello\'  : \'world\',
        \'number\' : 3
    }
    js = json.dumps(data)

    resp = Response(js, status=200, mimetype=\'application/json\')
    resp.headers[\'Link\'] = \'http://luisrei.com\'

    return resp

使用-i选项可以获取响应信息：

curl -i http://127.0.0.1:5000/hello

返回的响应信息如下所示：

GET /hello
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 31
Link: http://luisrei.com
Server: Werkzeug/0.8.2 Python/2.7.1
Date: Wed, 25 Apr 2012 16:40:27 GMT
{\"hello\": \"world\", \"number\": 3}

mimetype指定了响应数据的类型。
上面的过程可以使用Flask提供的一个简便方法实现：

from flask import jsonify
...
# 将下面的代码替换成
resp = Response(js, status=200, mimetype=\'application/json\')
# 这里的代码
resp = jsonify(data)
resp.status_code = 200

状态码和错误处理

如果成功响应的话，状态码为200。对于404错误我们可以这样处理：

@app.errorhandler(404)
def not_found(error=None):
    message = {
            \'status\': 404,
            \'message\': \'Not Found: \' + request.url,
    }
    resp = jsonify(message)
    resp.status_code = 404

    return resp

@app.route(\'/users/\', methods = [\'GET\'])
def api_users(userid):
    users = {\'1\':\'john\', \'2\':\'steve\', \'3\':\'bill\'}
    
    if userid in users:
        return jsonify({userid:users[userid]})
    else:
        return not_found()

测试上面的两个URL，结果如下：

GET /users/2
HTTP/1.0 200 OK
{
    \"2\": \"steve\"
}

GET /users/4
HTTP/1.0 404 NOT FOUND
{
\"status\": 404, 
\"message\": \"Not Found: http://127.0.0.1:5000/users/4\"
}

默认的Flask错误处理可以使用@error_handler修饰器进行覆盖或者使用下面的方法：

app.error_handler_spec[None][404] = not_found

即使API不需要自定义错误信息，最好还是像上面这样做，因为Flask默认返回的错误信息是HTML格式的。

认证

使用下面的代码可以处理 HTTP Basic Authentication。

from functools import wraps

def check_auth(username, password):
    return username == \'admin\' and password == \'secret\'

def authenticate():
    message = {\'message\': \"Authenticate.\"}
    resp = jsonify(message)

    resp.status_code = 401
    resp.headers[\'WWW-Authenticate\'] = \'Basic realm=\"Example\"\'

    return resp

def requires_auth(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        auth = request.authorization
        if not auth: 
            return authenticate()

        elif not check_auth(auth.username, auth.password):
            return authenticate()
        return f(*args, **kwargs)

    return decorated

接下来只需要给路由增加@require_auth修饰器就可以在请求之前进行认证了：

@app.route(\'/secrets\')
@requires_auth
def api_hello():
    return \"Shhh this is top secret spy stuff!\"

现在，如果没有通过认证的话，响应如下所示：

GET /secrets
HTTP/1.0 401 UNAUTHORIZED
WWW-Authenticate: Basic realm=\"Example\"
{
  \"message\": \"Authenticate.\"
}

curl通过-u选项来指定HTTP basic authentication，使用-v选项打印请求头：

curl -v -u \"admin:secret\" http://127.0.0.1:5000/secrets

响应结果如下：

GET /secrets Authorization: Basic YWRtaW46c2VjcmV0
Shhh this is top secret spy stuff!

Flask使用MultiDict来存储头部信息，为了给客户端展示不同的认证机制，可以给header添加更多的WWW-Autheticate。

resp.headers[\'WWW-Authenticate\'] = \'Basic realm=\"Example\"\'resp.headers.add(\'WWW-Authenticate\', \'Bearer realm=\"Example\"\')

调试与日志

通过设置debug=True来开启调试信息：

app.run(debug=True)

使用Python的logging模块可以设置日志信息：

import logging
file_handler = logging.FileHandler(\'app.log\')
app.logger.addHandler(file_handler)
app.logger.setLevel(logging.INFO)

@app.route(\'/hello\', methods = [\'GET\'])
def api_hello():
    app.logger.info(\'informing\')
    app.logger.warning(\'warning\')
    app.logger.error(\'screaming bloody murder!\')
    
    return \"check your logs\\n\"

CURL 命令参考