摘要：中使用類字典對象來獲取請求頭信息，使用獲取請求數(shù)據(jù)，如果發(fā)送類型是，則可以使用來獲取數(shù)據(jù)。響應(yīng)使用類處理響應(yīng)。認(rèn)證使用下面的代碼可以處理。

原創(chuàng)譯文，如需轉(zhuǎn)載，請聯(lián)系譯者。 
我的簡書博客:nummy

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

首先，安裝Flask

pip install flask

閱讀這篇文章之前我假設(shè)你已經(jīng)了解RESTful API的相關(guān)概念，如果不清楚，可以閱讀我之前寫的這篇博客[Designing a RESTful Web API.](http://blog.luisrei.com/articles/rest.html)

Flask是一個使用Python開發(fā)的基于Werkzeug的Web框架。
Flask非常適合于開發(fā)RESTful API，因為它具有以下特點：

使用Python進(jìn)行開發(fā)，Python簡潔易懂

容易上手

靈活

可以部署到不同的環(huán)境

支持RESTful請求分發(fā)

我一般是用curl命令進(jìn)行測試，除此之外，還可以使用Chrome瀏覽器的postman擴(kuò)展。

首先，我創(chuàng)建一個完整的應(yīng)用，支持響應(yīng)/, /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命令發(fā)送請求：

curl http://127.0.0.1:5000/

響應(yīng)結(jié)果分別如下所示：

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/")

默認(rèn)的類型為字符串。

請求參數(shù)

假設(shè)需要響應(yīng)一個/hello請求，使用get方法，并傳遞參數(shù)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"

服務(wù)器會返回如下響應(yīng)信息：

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
"

    elif request.method == "POST":
        return "ECHO: POST
"

    elif request.method == "PATCH":
        return "ECHO: PACTH
"

    elif request.method == "PUT":
        return "ECHO: PUT
"

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

可以使用如下命令進(jìn)行測試:

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

不同請求方法的響應(yīng)如下：

GET /echo
ECHO: GET

POST /ECHO
ECHO: POST
...

請求數(shù)據(jù)和請求頭

通常使用POST方法和PATCH方法的時候，都會發(fā)送附加的數(shù)據(jù)，這些數(shù)據(jù)的格式可能如下：普通文本(plain text)， JSON，XML，二進(jìn)制文件或者用戶自定義格式。
Flask中使用request.headers類字典對象來獲取請求頭信息，使用request.data 獲取請求數(shù)據(jù)，如果發(fā)送類型是application/json，則可以使用request.get_json()來獲取JSON數(shù)據(jù)。

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

使用如下命令指定請求數(shù)據(jù)類型進(jìn)行測試：

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

使用下面的curl命令來發(fā)送一個文件:

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

不同數(shù)據(jù)類型的響應(yīng)結(jié)果如下所示：

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類處理響應(yīng)。

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選項可以獲取響應(yīng)信息：

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

返回的響應(yīng)信息如下所示：

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指定了響應(yīng)數(shù)據(jù)的類型。
上面的過程可以使用Flask提供的一個簡便方法實現(xiàn)：

from flask import jsonify
...
# 將下面的代碼替換成
resp = Response(js, status=200, mimetype="application/json")
# 這里的代碼
resp = jsonify(data)
resp.status_code = 200

狀態(tài)碼和錯誤處理

如果成功響應(yīng)的話，狀態(tài)碼為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，結(jié)果如下：

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"
}

默認(rèn)的Flask錯誤處理可以使用@error_handler修飾器進(jìn)行覆蓋或者使用下面的方法：

app.error_handler_spec[None][404] = not_found

即使API不需要自定義錯誤信息，最好還是像上面這樣做，因為Flask默認(rèn)返回的錯誤信息是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修飾器就可以在請求之前進(jìn)行認(rèn)證了：

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

現(xiàn)在，如果沒有通過認(rèn)證的話，響應(yīng)如下所示：

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

響應(yīng)結(jié)果如下：

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

Flask使用MultiDict來存儲頭部信息，為了給客戶端展示不同的認(rèn)證機(jī)制，可以給header添加更多的WWW-Autheticate。

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

通過設(shè)置debug=True來開啟調(diào)試信息：

app.run(debug=True)

使用Python的logging模塊可以設(shè)置日志信息：

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
"

?