Flask 系列 - 基于 Flask 提供 RESTful Web 服务

什么是 REST

REST 全称是 Representational State Transfer,翻译成中文是『表现层状态转移』,估计读者看到这个词也是云里雾里的,我当初也是!这里,我们先不纠结这个词到底是什么意思。事实上,REST 是一种 Web 架构风格,它有六条准则,满足下面六条准则的 Web 架构可以说是 Restuful 的。

  1. 客户端-服务器(Client-Server)服务器和客户端之间有明确的界限。一方面,服务器端不再关注用户界面和用户状态。另一方面,客户端不再关注数据的存储问题。这样,服务器端跟客户端可以独立开发,只要它们共同遵守约定。
  2. 无状态(Stateless)来自客户端的每个请求必须包含服务器所需要的所有信息,也就是说,服务器端不存储来自客户端的某个请求的信息,这些信息应由客户端负责维护。
  3. 可缓存(Cachable)服务器的返回内容可以在通信链的某处被缓存,以减少交互次数,提高网络效率。
  4. 分层系统(Layered System)允许在服务器和客户端之间通过引入中间层(比如代理,网关等)代替服务器对客户端的请求进行回应,而且这些对客户端来说不需要特别支持。
  5. 统一接口(Uniform Interface)客户端和服务器之间通过统一的接口(比如 GET, POST, PUT, DELETE 等)相互通信。
  6. 支持按需代码(Code-On-Demand,可选)服务器可以提供一些代码(比如 Javascript)并在客户端中执行,以扩展客户端的某些功能。

使用 Flask 提供 REST Web 服务

REST Web 服务的核心概念是资源(resources)。资源被 URI(Uniform Resource Identifier, 统一资源标识符)定位,客户端使用 HTTP 协议操作这些资源,我们用一句不是很全面的话来概括就是:URI 定位资源,用 HTTP 动词(GET, POST, PUT, DELETE 等)描述操作。下面列出了 REST 架构 API 中常用的请求方法及其含义:

HTTP Method Action Example
GET 从某种资源获取信息 http://example.com/api/articles (获取所有文章)
GET 从某个资源获取信息 http://example.com/api/articles/1 (获取某篇文章)
POST 创建新资源 http://example.com/api/articles (创建新文章)
PUT 更新资源 http://example.com/api/articles/1 (更新文章)
DELETE 删除资源 http://example.com/api/articels/1 (删除文章)

设计一个简单的 Web Service

现在假设我们要为一个 blog 应用设计一个 Web Service。

首先,我们先明确访问该 Service 的根地址是什么。这里,我们可以这样定义:

然后,我们明确有哪些资源是要公开的。可以知道,我们这个 blog 应用的资源就是 articles。

下一步,我们要明确怎么去操作这些资源,如下所示:

HTTP Method URI Action
GET http://[hostname]/blog/api/articles 获取所有文章列表
GET http://[hostname]/blog/api/articles/[article_id] 获取某篇文章内容
POST http://[hostname]/blog/api/articles 创建一篇新的文章
PUT http://[hostname]/blog/api/articles/[article_id] 更新某篇文章
DELETE http://[hostname]/blog/api/articles/[article_id] 删除某篇文章

为了简便,我们定义一篇 article 的属性如下:

  • id:文章的 id,Numeric 类型
  • title: 文章的标题,String 类型
  • content: 文章的内容,TEXT 类型

至此,我们基本完成了这个 Web Service 的设计,下面我们就来实现它。

使用 Flask 提供 RESTful api

在实现这个 Web 服务之前,我们还有一个问题没有考虑到:我们应该怎么存储我们的数据。毫无疑问,我们应该使用数据库,比如 MySql、MongoDB 等。但是,数据库的存储不是我们这里要讨论的重点,所以我们采用一种偷懒的做法:使用一个内存中的数据结构来代替数据库。

GET 方法

下面我们使用 GET 方法获取资源。

将上面的代码保存为文件 app.py,通过 python app.py 启动这个 Web Service。

接下来,我们进行测试。这里,我们采用命令行语句 curl 进行测试。

开启终端,敲入如下命令进行测试:

上面,我们分别测试了『获取所有文章列表』、『获取某篇文章』和『获取不存在的文章』这三个功能,结果也正是我们所预料的。

POST 方法

下面我们使用 POST 方法创建一个新的资源。在上面的代码中添加以下代码:

测试如下:

可以看到,创建一篇新的文章也是很简单的。request.json 保存了请求中的 JSON 格式的数据。如果请求中没有数据,或者数据中没有 title 的内容,我们将会返回一个 “Bad Request” 的 400 错误。如果数据合法(必须要有 title 的字段),我们就会创建一篇新的文章。

PUT 方法

下面我们使用 PUT 方法更新文章,继续添加代码:

测试如下:

可以看到,更新文章也是很简单的,上面我们更新了第 2 篇文章的内容。

DELETE 方法

下面我们使用 DELETE 方法删除文章,继续添加代码:

测试如下:

附录

常见 HTTP 状态码

HTTP 状态码主要有以下几类:

  • 1xx —— 元数据
  • 2xx —— 正确的响应
  • 3xx —— 重定向
  • 4xx —— 客户端错误
  • 5xx —— 服务端错误

常见的 HTTP 状态码可见以下表格:

代码 说明
100 Continue。客户端应当继续发送请求。
200 OK。请求已成功,请求所希望的响应头或数据体将随此响应返回。
201 Created。请求成功,并且服务器创建了新的资源。
301 Moved Permanently。请求的网页已永久移动到新位置。 服务器返回此响应(对 GET 或 HEAD 请求的响应)时,会自动将请求者转到新位置。
302 Found。服务器目前从不同位置的网页响应请求,但请求者应继续使用原有位置来进行以后的请求。
400 Bad Request。服务器不理解请求的语法。
401 Unauthorized。请求要求身份验证。 对于需要登录的网页,服务器可能返回此响应。
403 Forbidden。服务器拒绝请求。
404 Not Found。服务器找不到请求的网页。
500 Internal Server Error。服务器遇到错误,无法完成请求。

curl 命令参考

选项 作用
-X 指定 HTTP 请求方法,如 POST,GET, PUT
-H 指定请求头,例如 Content-type:application/json
-d 指定请求数据
–data-binary 指定发送的文件
-i 显示响应头部信息
-u 指定认证用户名与密码
-v 输出请求头部信息

完整代码

本文的完整代码可在 Gist 查看。

参考链接

1 4 收藏 评论

相关文章

可能感兴趣的话题



直接登录
跳到底部
返回顶部