使用 Python 和 Flask 设计 RESTful API - 使用 Python 和 Flask 实现 RESTful services - 《使用 Flask 设计 RESTful APIs》

使用 Python 和 Flask 实现 RESTful services

使用 Python 和 Flask 实现 RESTful services

使用 Flask 构建 web services 是十分简单地，比我在 Mega-Tutorial 中构建的完整的服务端的应用程序要简单地多。

在 Flask 中有许多扩展来帮助我们构建 RESTful services，但是在我看来这个任务十分简单，没有必要使用 Flask 扩展。

我们 web service 的客户端需要添加、删除以及修改任务的服务，因此显然我们需要一种方式来存储任务。最直接的方式就是建立一个小型的数据库，但是数据库并不是本文的主体。学习在 Flask 中使用合适的数据库，我强烈建议阅读 Mega-Tutorial。

这里我们直接把任务列表存储在内存中，因此这些任务列表只会在 web 服务器运行中工作，在结束的时候就失效。这种方式只是适用我们自己开发的 web 服务器，不适用于生产环境的 web 服务器，这种情况一个合适的数据库的搭建是必须的。

我们现在来实现 web service 的第一个入口:

1. #!flask/bin/python
2. from flask import Flask, jsonify

4. app = Flask(__name__)

6. tasks = [
7. {
8. 'id': 1,
9. 'title': u'Buy groceries',
10. 'description': u'Milk, Cheese, Pizza, Fruit, Tylenol',
11. 'done': False
12. },
13. {
14. 'id': 2,
15. 'title': u'Learn Python',
16. 'description': u'Need to find a good Python tutorial on the web',
17. 'done': False
18. }
19. ]

21. @app.route('/todo/api/v1.0/tasks', methods=['GET'])
22. def get_tasks():
23. return jsonify({'tasks': tasks})

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

正如你所见，没有多大的变化。我们创建一个任务的内存数据库，这里无非就是一个字典和数组。数组中的每一个元素都具有上述定义的任务的属性。

取代了首页，我们现在拥有一个 get_tasks 的函数，访问的 URI 为 /todo/api/v1.0/tasks，并且只允许 GET 的 HTTP 方法。

这个函数的响应不是文本，我们使用 JSON 数据格式来响应，Flask 的 jsonify 函数从我们的数据结构中生成。

使用网页浏览器来测试我们的 web service 不是一个最好的注意，因为网页浏览器上不能轻易地模拟所有的 HTTP 请求的方法。相反，我们会使用 curl。如果你还没有安装 curl 的话，请立即安装它。

通过执行 app.py，启动 web service。接着打开一个新的控制台窗口，运行以下命令:

1. $ curl -i http://localhost:5000/todo/api/v1.0/tasks
2. HTTP/1.0 200 OK
3. Content-Type: application/json
4. Content-Length: 294
5. Server: Werkzeug/0.8.3 Python/2.7.3
6. Date: Mon, 20 May 2013 04:53:53 GMT

8. {
9. "tasks": [
10. {
11. "description": "Milk, Cheese, Pizza, Fruit, Tylenol",
12. "done": false,
13. "id": 1,
14. "title": "Buy groceries"
15. },
16. {
17. "description": "Need to find a good Python tutorial on the web",
18. "done": false,
19. "id": 2,
20. "title": "Learn Python"
21. }
22. ]
23. }

我们已经成功地调用我们的 RESTful service 的一个函数！

现在我们开始编写 GET 方法请求我们的任务资源的第二个版本。这是一个用来返回单独一个任务的函数:

1. from flask import abort

3. @app.route('/todo/api/v1.0/tasks/<int:task_id>', methods=['GET'])
4. def get_task(task_id):
5. task = filter(lambda t: t['id'] == task_id, tasks)
6. if len(task) == 0:
7. abort(404)
8. return jsonify({'task': task[0]})

第二个函数有些意思。这里我们得到了 URL 中任务的 id，接着 Flask 把它转换成函数中的 task_id 的参数。

我们用这个参数来搜索我们的任务数组。如果我们的数据库中不存在搜索的 id，我们将会返回一个类似 404 的错误，根据 HTTP 规范的意思是 “资源未找到”。

如果我们找到相应的任务，那么我们只需将它用 jsonify 打包成 JSON 格式并将其发送作为响应，就像我们以前那样处理整个任务集合。

调用 curl 请求的结果如下:

1. $ curl -i http://localhost:5000/todo/api/v1.0/tasks/2
2. HTTP/1.0 200 OK
3. Content-Type: application/json
4. Content-Length: 151
5. Server: Werkzeug/0.8.3 Python/2.7.3
6. Date: Mon, 20 May 2013 05:21:50 GMT

8. {
9. "task": {
10. "description": "Need to find a good Python tutorial on the web",
11. "done": false,
12. "id": 2,
13. "title": "Learn Python"
14. }
15. }
16. $ curl -i http://localhost:5000/todo/api/v1.0/tasks/3
17. HTTP/1.0 404 NOT FOUND
18. Content-Type: text/html
19. Content-Length: 238
20. Server: Werkzeug/0.8.3 Python/2.7.3
21. Date: Mon, 20 May 2013 05:21:52 GMT

23. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
24. <title>404 Not Found</title>
25. <h1>Not Found</h1>
26. <p>The requested URL was not found on the server.</p><p>If you     entered the URL manually please check your spelling and try again.</p>

当我们请求 id #2 的资源时候，我们获取到了，但是当我们请求 #3 的时候返回了 404 错误。有关错误奇怪的是返回的是 HTML 信息而不是 JSON，这是因为 Flask 按照默认方式生成 404 响应。由于这是一个 Web service 客户端希望我们总是以 JSON 格式回应，所以我们需要改善我们的 404 错误处理程序:

1. from flask import make_response

3. @app.errorhandler(404)
4. def not_found(error):
5. return make_response(jsonify({'error': 'Not found'}), 404)

我们会得到一个友好的错误提示:

1. $ curl -i http://localhost:5000/todo/api/v1.0/tasks/3
2. HTTP/1.0 404 NOT FOUND
3. Content-Type: application/json
4. Content-Length: 26
5. Server: Werkzeug/0.8.3 Python/2.7.3
6. Date: Mon, 20 May 2013 05:36:54 GMT

8. {
9. "error": "Not found"
10. }

接下来就是 POST 方法，我们用来在我们的任务数据库中插入一个新的任务:

1. from flask import request

3. @app.route('/todo/api/v1.0/tasks', methods=['POST'])
4. def create_task():
5. if not request.json or not 'title' in request.json:
6. abort(400)
7. task = {
8. 'id': tasks[-1]['id'] + 1,
9. 'title': request.json['title'],
10. 'description': request.json.get('description', ""),
11. 'done': False
12. }
13. tasks.append(task)
14. return jsonify({'task': task}), 201

添加一个新的任务也是相当容易地。只有当请求以 JSON 格式形式，request.json 才会有请求的数据。如果没有数据，或者存在数据但是缺少 title 项，我们将会返回 400，这是表示请求无效。

接着我们会创建一个新的任务字典，使用最后一个任务的 id + 1 作为该任务的 id。我们允许 description 字段缺失，并且假设 done 字段设置成 False。

我们把新的任务添加到我们的任务数组中，并且把新添加的任务和状态 201 响应给客户端。

使用如下的 curl 命令来测试这个新的函数:

1. $ curl -i -H "Content-Type: application/json" -X POST -d '{"title":"Read a book"}' http://localhost:5000/todo/api/v1.0/tasks
2. HTTP/1.0 201 Created
3. Content-Type: application/json
4. Content-Length: 104
5. Server: Werkzeug/0.8.3 Python/2.7.3
6. Date: Mon, 20 May 2013 05:56:21 GMT

8. {
9. "task": {
10. "description": "",
11. "done": false,
12. "id": 3,
13. "title": "Read a book"
14. }
15. }

注意：如果你在 Windows 上并且运行 Cygwin 版本的 curl，上面的命令不会有任何问题。然而，如果你使用原生的 curl，命令会有些不同:

1. curl -i -H "Content-Type: application/json" -X POST -d "{"""title""":"""Read a book"""}" http://localhost:5000/todo/api/v1.0/tasks

当然在完成这个请求后，我们可以得到任务的更新列表:

1. $ curl -i http://localhost:5000/todo/api/v1.0/tasks
2. HTTP/1.0 200 OK
3. Content-Type: application/json
4. Content-Length: 423
5. Server: Werkzeug/0.8.3 Python/2.7.3
6. Date: Mon, 20 May 2013 05:57:44 GMT

8. {
9. "tasks": [
10. {
11. "description": "Milk, Cheese, Pizza, Fruit, Tylenol",
12. "done": false,
13. "id": 1,
14. "title": "Buy groceries"
15. },
16. {
17. "description": "Need to find a good Python tutorial on the web",
18. "done": false,
19. "id": 2,
20. "title": "Learn Python"
21. },
22. {
23. "description": "",
24. "done": false,
25. "id": 3,
26. "title": "Read a book"
27. }
28. ]
29. }

剩下的两个函数如下所示:

1. @app.route('/todo/api/v1.0/tasks/<int:task_id>', methods=['PUT'])
   def update_task(task_id):
       task = filter(lambda t: t['id'] == task_id, tasks)
       if len(task) == 0:
           abort(404)
       if not request.json:
           abort(400)
       if 'title' in request.json and type(request.json['title']) != unicode:
           abort(400)
       if 'description' in request.json and type(request.json['description']) is not unicode:
           abort(400)
       if 'done' in request.json and type(request.json['done']) is not bool:
           abort(400)
       task[0]['title'] = request.json.get('title', task[0]['title'])
       task[0]['description'] = request.json.get('description', task[0]['description'])
       task[0]['done'] = request.json.get('done', task[0]['done'])
       return jsonify({'task': task[0]})
2. @app.route('/todo/api/v1.0/tasks/<int:task_id>', methods=['DELETE'])
   def delete_task(task_id):
       task = filter(lambda t: t['id'] == task_id, tasks)
       if len(task) == 0:
           abort(404)
       tasks.remove(task[0])
       return jsonify({'result': True})

delete_task 函数没有什么特别的。对于 update_task 函数，我们需要严格地检查输入的参数以防止可能的问题。我们需要确保在我们把它更新到数据库之前，任何客户端提供我们的是预期的格式。

更新任务 #2 的函数调用如下所示:

1. $ curl -i -H "Content-Type: application/json" -X PUT -d '{"done":true}' http://localhost:5000/todo/api/v1.0/tasks/2
2. HTTP/1.0 200 OK
3. Content-Type: application/json
4. Content-Length: 170
5. Server: Werkzeug/0.8.3 Python/2.7.3
6. Date: Mon, 20 May 2013 07:10:16 GMT

8. {
9. "task": [
10. {
11. "description": "Need to find a good Python tutorial on the web",
12. "done": true,
13. "id": 2,
14. "title": "Learn Python"
15. }
16. ]
17. }