Flask-RESTful 快速入門

是時候編寫你第一個 REST API。本指南假設你對 Flask 有必定的認識，而且已經安裝了 Flask 和 Flask-RESTful。

一個最小的 API

一個最小的 Flask-RESTful API 像這樣:

from flask import Flask
from flask_restful import Api, Resource

app = Flask(__name__)
api = Api(app)


class HelloWorld(Resource):
	def get(self):
		return {'hello': 'world'}


api.add_resource(HelloWorld, '/')

if __name__ == '__main__':
	app.run(debug=True)

資源豐富的路由(Resourceful Routing)

Flask-RESTful 提供的最主要的基礎就是資源(resources)。

資源(Resources)是構建在 Flask 可拔插視圖 之上，只要在你的資源(resource)上定義方法就可以容易地訪問多個 HTTP 方法。

一個待辦事項應用程序的基本的 CRUD 資源看起來像這樣:

todos = {}


class TodoSimple(Resource):
	def get(self, todo_id):
		return {todo_id: todos[todo_id]}

	def put(self, todo_id):
		todos[todo_id] = request.form['data']
		return {todo_id: todos[todo_id]}


api.add_resource(TodoSimple, '/<string:todo_id>')

Flask-RESTful 支持視圖方法多種類型的返回值。同 Flask 同樣，你能夠返回任一迭代器，它將會被轉換成一個包含原始 Flask 響應對象的響應。

Flask-RESTful 也支持使用多個返回值來設置響應代碼和響應頭，以下所示:

class Todo1(Resource):
    def get(self):
        # Default to 200 OK
        return {'task': 'Hello world'}

class Todo2(Resource):
    def get(self):
        # Set the response code to 201
        return {'task': 'Hello world'}, 201

class Todo3(Resource):
    def get(self):
        # Set the response code to 201 and return custom headers
        return {'task': 'Hello world'}, 201, {'Etag': 'some-opaque-string'}

端點(Endpoints)

不少時候在一個 API 中，你的資源能夠經過多個 URLs 訪問。你能夠把多個 URLs 傳給 Api 對象的 Api.add_resource() 方法。每個 URL 都能訪問到你的 Resource。

api.add_resource(HelloWorld,
    '/',
    '/hello')

你也能夠爲你的資源方法指定 endpoint 參數。

api.add_resource(Todo,
    '/todo/<int:todo_id>', endpoint='todo_ep')

參數解析

儘管 Flask 可以簡單地訪問請求數據(好比查詢字符串或者 POST 表單編碼的數據)，驗證表單數據仍然很痛苦。

Flask-RESTful 內置了支持驗證請求數據，它使用了一個相似 argparse 的庫。

parser = reqparse.RequestParser()
parser.add_argument('rate', type=int, help='Rate to charge for this resource')
args = parser.parse_args()

須要注意地是與 argparse 模塊不一樣，reqparse.RequestParser.parse_args() 返回一個 Python 字典而不是一個自定義的數據結構。

使用 reqparse 模塊一樣能夠自由地提供聰明的錯誤信息。若是參數沒有經過驗證，Flask-RESTful 將會以一個 400 錯誤請求以及高亮的錯誤信息迴應。

inputs 模塊提供了許多的常見的轉換函數，好比 inputs.date() 和 inputs.url()。

使用 strict=True 調用 parse_args 可以確保當請求包含你的解析器中未定義的參數的時候會拋出一個異常。

args = parser.parse_args(strict=True)

數據格式化

默認狀況下，在你的返回迭代中全部字段將會原樣呈現。

儘管當你剛剛處理 Python 數據結構的時候，以爲這是一個偉大的工做，可是當實際處理它們的時候，會以爲十分沮喪和枯燥。

爲了解決這個問題，Flask-RESTful 提供了 fields 模塊和 marshal_with() 裝飾器。

相似 Django ORM 和 WTForm，你可使用 fields 模塊來在你的響應中格式化結構。

from collections import OrderedDict
from flask.ext.restful import fields, marshal_with

resource_fields = {
    'task':   fields.String,
    'uri':    fields.Url('todo_ep')
}

class TodoDao(object):
    def __init__(self, todo_id, task):
        self.todo_id = todo_id
        self.task = task

        # This field will not be sent in the response
        self.status = 'active'

class Todo(Resource):
    @marshal_with(resource_fields)
    def get(self, **kwargs):
        return TodoDao(todo_id='my_todo', task='Remember the milk')

上面的例子接受一個 python 對象並準備將其序列化。marshal_with() 裝飾器將會應用到由 resource_fields 描述的轉換。

從對象中提取的惟一字段是 task。

fields.Url 域是一個特殊的域，它接受端點（endpoint）名稱做爲參數而且在響應中爲該端點生成一個 URL。

許多你須要的字段類型都已經包含在內。