Flask-RESTful

在前面，我们介绍了 REST Web 服务，并使用 Flask 提供服务。这里，我们使用第三方库 Flask-RESTful，它使得在 Flask 中提供 REST 服务变得更加简单。

安装

使用 pip 安装：

  1. $ pip install flask-restful

使用

下面我们主要使用官方文档的例子进行说明。

Hello World

我们先来看一个简单的例子。

  1. # -*- coding: utf-8 -*-
  3. from flask import Flask
  4. from flask_restful import Resource, Api
  6. app = Flask(__name__)
  7. api = Api(app)
  9. class HelloWorld(Resource):
  10.     def get(self):
  11.         return {'hello': 'world'}
  13. api.add_resource(HelloWorld, '/')
  15. if __name__ == '__main__':
  16.     app.run(debug=True)

上面的代码应该不难看懂。我们定义了一个 HelloWorld 的类，该类继承自 Resource，在类里面，我们定义了 get 方法，该方法跟 HTTP 请求中的 GET 方法对应。接着，我们使用 add_resource() 方法添加资源，该方法的第 1 个参数就是我们定义的类，第 2 个参数是 URL 路由。

将上面的代码保存为 app.py，在终端运行：

  1. $ python app.py
  2.  * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
  3.  * Restarting with stat
  4.  * Debugger is active!
  5.  * Debugger pin code: 109-566-036

使用 curl 测试，如下：

  1. $ curl http://127.0.0.1:5000/
  2. {
  3.     "hello": "world"
  4. }

另外，add_resource() 方法也支持添加多个路由，比如：

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

这样访问 http://127.0.0.1:5000/ 和 http://127.0.0.1:5000/hello 效果是一样的。

带参数的请求

Flask-RESTful 也支持路由带参数的请求，跟 Flask 的实现是类似的，看下面这个例子。

  1. # -*- coding: utf-8 -*-
  3. from flask import Flask, request
  4. from flask_restful import Resource, Api
  6. app = Flask(__name__)
  7. api = Api(app)
  9. todos = {}
  11. class TodoSimple(Resource):
  12.     def get(self, todo_id):
  13.         return {todo_id: todos[todo_id]}
  15.     def put(self, todo_id):
  16.         todos[todo_id] = request.form['data']
  17.         return {todo_id: todos[todo_id]}
  19. # 路由带参数
  20. api.add_resource(TodoSimple, '/<string:todo_id>')
  22. if __name__ == '__main__':
  23.     app.run(debug=True)

使用 curl 测试，如下：

  1. $ curl -X PUT http://localhost:5000/todo1 -d "data=shopping"
  2. {
  3.     "todo1": "shopping"
  4. }
  6. $ curl -X GET http://localhost:5000/todo1
  7. {
  8.     "todo1": "shopping"
  9. }

参数解析

Flask-RESTful 提供了 reqparse 库来简化我们访问并验证表单的工作，将上面的代码使用 reqparse 改写，如下：

  1. # -*- coding: utf-8 -*-
  3. from flask import Flask, request
  4. from flask_restful import Resource, Api, reqparse
  6. app = Flask(__name__)
  7. api = Api(app)
  9. parser = reqparse.RequestParser()
  10. parser.add_argument('task', type=str)  # 相当于添加 form 表单字段，并给出类型
  12. todos = {}
  14. class TodoSimple(Resource):
  15.     def get(self, todo_id):
  16.         return {todo_id: todos[todo_id]}
  18.     def put(self, todo_id):
  19.         args = parser.parse_args()   # 获取表单的内容, args 是一个字典
  20.         if args['task']:
  21.             todos[todo_id] = args['task']   
  22.         else:
  23.             return 'error!'
  25.         return {todo_id: todos[todo_id]}
  27. api.add_resource(TodoSimple, '/<string:todo_id>')
  29. if __name__ == '__main__':
  30.     app.run(debug=True)

上面的代码中，我们使用 add_argument() 方法添加 form 表单字段，并指定其类型。获取表单内容使用 parse_args() 方法，该方法返回一个字典，字典的 key 就是表单的字段。

使用 curl 测试，如下：

  1. $ curl -X PUT http://localhost:5000/todo1 -d "task=shopping"
  2. {
  3.     "todo1": "shopping"
  4. }

一个完整的例子

下面这个完整的例子来自于官方文档。

  1. from flask import Flask
  2. from flask_restful import reqparse, abort, Api, Resource
  4. app = Flask(__name__)
  5. api = Api(app)
  7. TODOS = {
  8.     'todo1': {'task': 'build an API'},
  9.     'todo2': {'task': '?????'},
  10.     'todo3': {'task': 'profit!'},
  11. }
  13. def abort_if_todo_doesnt_exist(todo_id):
  14.     if todo_id not in TODOS:
  15.         abort(404, message="Todo {} doesn't exist".format(todo_id))
  17. parser = reqparse.RequestParser()
  18. parser.add_argument('task')
  20. # Todo
  21. # shows a single todo item and lets you delete a todo item
  22. class Todo(Resource):
  23.     def get(self, todo_id):
  24.         abort_if_todo_doesnt_exist(todo_id)
  25.         return TODOS[todo_id]
  27.     def delete(self, todo_id):
  28.         abort_if_todo_doesnt_exist(todo_id)
  29.         del TODOS[todo_id]
  30.         return '', 204
  32.     def put(self, todo_id):
  33.         args = parser.parse_args()
  34.         task = {'task': args['task']}
  35.         TODOS[todo_id] = task
  36.         return task, 201
  38. # TodoList
  39. # shows a list of all todos, and lets you POST to add new tasks
  40. class TodoList(Resource):
  41.     def get(self):
  42.         return TODOS
  44.     def post(self):
  45.         args = parser.parse_args()
  46.         todo_id = int(max(TODOS.keys()).lstrip('todo')) + 1
  47.         todo_id = 'todo%i' % todo_id
  48.         TODOS[todo_id] = {'task': args['task']}
  49.         return TODOS[todo_id], 201
  51. ## Actually setup the Api resource routing here
  52. api.add_resource(TodoList, '/todos')
  53. api.add_resource(Todo, '/todos/<todo_id>')
  55. if __name__ == '__main__':
  56.     app.run(debug=True)

运行上面的代码，然后使用 curl 进行测试，如下：

  1. # 获取所有 todos
  2. $ curl http://localhost:5000/todos
  3. {
  4.     "todo1": {
  5.         "task": "build an API"
  6.     },
  7.     "todo2": {
  8.         "task": "?????"
  9.     },
  10.     "todo3": {
  11.         "task": "profit!"
  12.     }
  13. }
  15. # 获取单个 todo
  16. $ curl http://localhost:5000/todos/todo2
  17. {
  18.     "task": "?????"
  19. }
  21. # 删除某个 todo
  22. $ curl -v -X DELETE http://localhost:5000/todos/todo2
  23. *   Trying 127.0.0.1...
  24. * Connected to localhost (127.0.0.1) port 5000 (#0)
  25. > DELETE /todos/todo2 HTTP/1.1
  26. > Host: localhost:5000
  27. > User-Agent: curl/7.43.0
  28. > Accept: */*
  29. >
  30. * HTTP 1.0, assume close after body
  31. < HTTP/1.0 204 NO CONTENT
  32. < Content-Type: application/json
  33. < Content-Length: 0
  34. < Server: Werkzeug/0.11.11 Python/2.7.11
  35. < Date: Tue, 18 Oct 2016 04:02:17 GMT
  36. <
  37. * Closing connection 0
  39. # 添加 todo
  40. $ curl -v -X POST http://localhost:5000/todos -d "task=eating"
  41. *   Trying 127.0.0.1...
  42. * Connected to localhost (127.0.0.1) port 5000 (#0)
  43. > POST /todos HTTP/1.1
  44. > Host: localhost:5000
  45. > User-Agent: curl/7.43.0
  46. > Accept: */*
  47. > Content-Length: 11
  48. > Content-Type: application/x-www-form-urlencoded
  49. >
  50. * upload completely sent off: 11 out of 11 bytes
  51. * HTTP 1.0, assume close after body
  52. < HTTP/1.0 201 CREATED
  53. < Content-Type: application/json
  54. < Content-Length: 25
  55. < Server: Werkzeug/0.11.11 Python/2.7.11
  56. < Date: Tue, 18 Oct 2016 04:04:16 GMT
  57. <
  58. {
  59.     "task": "eating"
  60. }
  61. * Closing connection 0
  63. # 更新 todo
  64. $ curl -v -X PUT http://localhost:5000/todos/todo3 -d "task=running"
  65. *   Trying 127.0.0.1...
  66. * Connected to localhost (127.0.0.1) port 5000 (#0)
  67. > PUT /todos/todo3 HTTP/1.1
  68. > Host: localhost:5000
  69. > User-Agent: curl/7.43.0
  70. > Accept: */*
  71. > Content-Length: 12
  72. > Content-Type: application/x-www-form-urlencoded
  73. >
  74. * upload completely sent off: 12 out of 12 bytes
  75. * HTTP 1.0, assume close after body
  76. < HTTP/1.0 201 CREATED
  77. < Content-Type: application/json
  78. < Content-Length: 26
  79. < Server: Werkzeug/0.11.11 Python/2.7.11
  80. < Date: Tue, 18 Oct 2016 04:05:52 GMT
  81. <
  82. {
  83.     "task": "running"
  84. }
  85. * Closing connection 0

本文完整的代码在这里。

更多阅读