簡介
首先，安裝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。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
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/ |
響應結果分別如下所示：
|
1 2 3 4 5 6 7 8 |
GET / Welcome GET /articles List of /articles GET /articles/123 You are reading 123 |
路由中還可以使用型別定義:
|
1 |
@app.route('/articles/<articleid>') |
上面的路由可以替換成下面的例子：
|
1 2 3 |
@app.route('/articles/<int:articleid>') @app.route('/articles/<float:articleid>') @app.route('/articles/<path:articleid>') |
預設的型別為字串。
請求REQUESTS
請求引數
假設需要響應一個/hello請求，使用get方法，並傳遞引數name
|
1 2 3 4 5 6 7 8 |
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' |
伺服器會返回如下響應資訊：
|
1 2 3 4 5 |
GET /hello Hello John Doe GET /hello?name=Luis Hello Luis |
請求方法
Flask支援不同的請求方法：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
@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 |
不同請求方法的響應如下：
|
1 2 3 4 5 6 |
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資料。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
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 |
不同資料型別的響應結果如下所示：
|
1 2 3 4 5 6 7 |
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類處理響應。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
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 |
返回的響應資訊如下所示：
|
1 2 3 4 5 6 7 8 |
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提供的一個簡便方法實現：
|
1 2 3 4 5 6 7 |
from flask import jsonify ... # 將下面的程式碼替換成 resp = Response(js, status=200, mimetype='application/json') # 這裡的程式碼 resp = jsonify(data) resp.status_code = 200 |
狀態碼和錯誤處理
如果成功響應的話，狀態碼為200。對於404錯誤我們可以這樣處理：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
@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，結果如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 |
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。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
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修飾器就可以在請求之前進行認證了：
|
1 2 3 4 |
@app.route('/secrets') @requires_auth def api_hello(): return "Shhh this is top secret spy stuff!" |
現在，如果沒有通過認證的話，響應如下所示：
|
1 2 3 4 5 6 |
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模組可以設定日誌資訊：
|
1 2 3 4 5 6 7 8 9 10 11 12 |
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 | 輸出請求頭部資訊 |