使用 Flask 实现 RESTful API

原文出处： Luis Rei 译文出处：nummy

简介

首先，安装Flask

1	pip install flask

假设那你已经了解RESTful API的相关概念，如果不清楚，可以阅读我之前写的这篇博客Designing a RESTful Web API.

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

使用Python进行开发，Python简洁易懂
容易上手
灵活
可以部署到不同的环境
支持RESTful请求分发

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

资源

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

Python

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/<articleid>')

def api_article(articleid):

return 'You are reading ' + articleid

if __name__ == '__main__':

app.run()

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

1	curl http://127.0.0.1:5000/

响应结果分别如下所示：

GET /

Welcome

GET /articles

List of /articles

GET /articles/123

You are reading 123

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

1	@app.route('/articles/<articleid>')

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

@app.route('/articles/<int:articleid>')

@app.route('/articles/<float:articleid>')

@app.route('/articles/<path:articleid>')

默认的类型为字符串。

请求REQUESTS

请求参数

假设需要响应一个/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"

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

1	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 ;)"

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

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

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

1 2	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 <message.bin>

Content-type: application/octet-stream

Binary message written!

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

响应RESPONSES

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选项可以获取响应信息：

1	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/<userid>', 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修饰器进行覆盖或者使用下面的方法：

1	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选项打印请求头：

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

响应结果如下：

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

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

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

调试与日志

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

1	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 命令参考

选项	作用
-X	指定HTTP请求方法，如POST，GET
-H	指定请求头，例如Content-type:application/json
-d	指定请求数据
–data-binary	指定发送的文件
-i	显示响应头部信息
-u	指定认证用户名与密码
-v	输出请求头部信息