Question

系统间协作及使用外部服务时，经常会用 REST API 作接口。REST API 可以用 Python 标准模块 urllib 和 json 来控制，不过本书要讲的是 Requests 的使用方法。

Requests: HTTP for Humans

http://docs.python-requests.org/en/latest/

15.6.1　REST 简介

REST（Representational state transfer，具象状态传输 1 ）是一种软件架构。它于 2000 年由 Roy Fielding 提出，是几种软件设计原则的集合。

1 有时也被译为表述性状态转移或表述性状态传输等。——译者注

不过，现在人们广泛使用的 REST 和 REST API 通常指“在 HTTP 上运行的非 SOAP 非 RPC 的 API”。

REST API 的特征如下。

· 在 HTTP 上运行

· 数据被称为“资源”

· REST API 可使用的资源具有唯一的 URL

· GET/POST/PUT/DELETE 等 HTTP 方法分别对应资源的获取 / 保存 / 覆盖 / 删除等操作

· 通过 JSON、XML 等格式收发数据

· 请求成功、请求失败等处理结果体现在状态代码中

如果要使用 REST API，则需要用到 HTTP 客户端。在 shell 命令或 shell 脚本中使用时要用 curl，在程序中使用时则要用 HTTP 客户端程序库。

REST - Wikipedia

http://zh.wikipedia.org/wiki/REST

Fielding Dissertation CHAPTER 5 Representational State Transfer (REST)

http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

15.6.2　导入 Requests

如 LIST 15.44 所示，用 pip 命令安装 Requests。本书使用的是 Requests 的 2.5.0 版本。

LIST 15.44　用 pip 命令安装 Requests

$ pip install requests

15.6.3　导入测试服务器

要检查 Requests 模块的运行状况就必须使用 Web 服务器。httpbin 模块是基于 Python 开发的 HTTP 测试服务器。本书将用 httpbin 模块作为测试服务器来讲解 Requests 的使用方法。

如 LIST 15.45 所示，用 pip 命令安装 httpbin。本书使用的是 httpbin 的 0.2.0 版本。

LIST 15.45　用 pip 命令安装 httpbin

$ pip install httpbin

httpbin 的测试服务器用 LIST 15.46 中的命令启动。

LIST 15.46　启动 httpbin 的测试服务器

$ python -m httpbin.core
 * Running on http://127.0.0.1:5000/

在导入 Requests 模块之前，先用 curl 命令检查测试服务器的运行状况。

在测试服务器已启动的状态下运行 LIST 15.47。如果运行正常，屏幕上将显示如下所示的 JSON 格式报告。

LIST 15.47　用 curl 命令检查测试服务器的运行状况

$ curl "http://127.0.0.1:5000/get?foo=bar"  # 向测试服务器发送GET 请求
{
  "args": {  # args 为GET 参数
  "foo": "bar"
  },
  "headers": {
  "Accept": "*/*",
  "Content-Length": "",
  "Content-Type": "",
  "Host": "127.0.0.1:5000",
  "User-Agent": "curl/7.35.0"
  },
  "origin": "127.0.0.1",
  "url": "http://127.0.0.1:5000/get?foo=bar"
}
$ curl -X post -d foo=bar http://127.0.0.1:5000/post  # 向测试服务器发送POST 请求
{
  "args": {},
  "data": "",  # data 为发送数据的正文（未经过编码的表单数据除外）
  "files": {},  # files 为被上传的文件
  "form": {  # form 为经过编码的表单数据
  "foo": "bar"
  },
  "headers": {
  "Accept": "*/*",
  "Content-Length": "7",
  "Content-Type": "application/x-www-form-urlencoded",
  "Host": "127.0.0.1:5000",
  "User-Agent": "curl/7.35.0"
  },
  "json": null,
  "origin": "127.0.0.1",
  "url": "http://127.0.0.1:5000/post"
}

可以看出，测试服务器具有将请求的内容以 JSON 格式返回的功能。

NOTE

在 Windows 上使用curl 命令时需要安装命令工具。

cURL - Download

http://curl.haxx.se/download.html

15.6.4　发送GET 请求

用 Requests 发送 GET 请求，具体代码如 LIST 15.48 所示。

LIST 15.48　requests_get.py

# coding: utf-8
import pprint
import requests
def main():
  # GET 参数以字典形式通过params 传值参数指定
  response = requests.get(
    'http://127.0.0.1:5000/get',
    params={'foo': 'bar'})
  # 使用响应对象的json 方法可以获取转换为Python 字典对象的JSON 数据
  pprint.pprint(response.json())
if __name__ == '__main__':
  main()

在 requests.get 函数中指定对象 URL，用 params 关键字传值参数指定 GET 参数。服务器返回的响应为 JSON 格式，因此要用 json 方法将其转换为字典形式再显示到页面上。上述代码的执行结果如 LIST 15.49 所示。

LIST 15.49　执行结果

$ python requests_get.py
{u'args': {u'foo': u'bar'},
 u'headers': {u'Accept': u'*/*',
        u'Accept-Encoding': u'gzip, deflate',
        u'Connection': u'keep-alive',
        u'Content-Length': u'',
        u'Content-Type': u'',
        u'Host': u'127.0.0.1:5000',
        u'User-Agent': u'python-requests/2.5.0 CPython/2.7.8 Linux/3.13.0-35-generic'},
 u'origin': u'127.0.0.1',
 u'url': u'http://127.0.0.1:5000/get?foo=bar'}

15.6.5　发送 POST 请求

用 Requests 发送 POST 请求，具体代码如 LIST 15.50 所示。

LIST 15.50　requests_post.py

# coding: utf-8
import pprint
import requests
def main():
  # POST 参数以字典形式通过第二个传值参数指定
  response = requests.post(
    'http://127.0.0.1:5000/post',
    {'foo': 'bar'})
  # 使用响应对象的json 方法可以获取转换为Python 字典对象的JSON 数据
  pprint.pprint(response.json())
if __name__ == '__main__':
  main()

request.post 函数中指定了对象 URL 和 POST 参数。给 POST 参数指定的字典会被编码为 URL 发送出去。这段代码的执行结果如 LIST 15.51 所示。

LIST 15.51　执行结果

$ python requests_post.py
{u'args': {},
 u'data': u'',
 u'files': {},
 u'form': {u'foo': u'bar'},
 u'headers': {u'Accept': u'*/*',
        u'Accept-Encoding': u'gzip, deflate',
        u'Connection': u'keep-alive',
        u'Content-Length': u'7',
        u'Content-Type': u'application/x-www-form-urlencoded',
        u'Host': u'127.0.0.1:5000',
        u'User-Agent': u'python-requests/2.5.0 CPython/2.7.8 Linux/3.13.0-35-generic'},
 u'json': None,
 u'origin': u'127.0.0.1',
 u'url': u'http://127.0.0.1:5000/post'}

15.6.6　发送 JSON 格式的 POST 请求

有些 API 接口要求直接发送 JSON 格式的字符串，不能将数据编码为 URL。用 Requests 以 JSON 格式字符串的形式发送 POST 请求，具体代码如 LIST 15.52 所示。

LIST 15.52　requests_post_json.py

# coding: utf-8
import pprint
import json
import requests
def main():
  # 指定json.dumps 生成的字符串之后，可以直接发送数据而不进行URL 编码
  # 需要明确指定Content-Tpye
  response = requests.post(
    'http://127.0.0.1:5000/post',
    json.dumps({'foo': 'bar'}),
    headers={'Content-Type': 'application/json'})
  pprint.pprint(response.json())
if __name__ == '__main__':
  main()

post 函数的传值参数中指定的发送数据为字符串。传值参数指定字符串时会直接发送数据，不进行 URL 编码。这段代码的执行结果如 LIST 15.53 所示。

LIST 15.53　执行结果

$ python requests_post_json.py
{u'args': {},
 u'data': u'{"foo": "bar"}',
 u'files': {},
 u'form': {},
 u'headers': {u'Accept': u'*/*',
        u'Accept-Encoding': u'gzip, deflate',
        u'Connection': u'keep-alive',
        u'Content-Length': u'14',
        u'Content-Type': u'application/json',
        u'Host': u'127.0.0.1:5000',
        u'User-Agent': u'python-requests/2.5.0 CPython/2.7.8 Linux/3.13.0-35-generic'},
 u'json': {u'foo': u'bar'},
 u'origin': u'127.0.0.1',
 u'url': u'http://127.0.0.1:5000/post'}

15.6.7　使用 GET/POST 之外的 HTTP 方法

某些 API 还会用到 GET、POST 之外的 HTTP 方法（PUT、DELETE、HEAD、OPTIONS）。Requests 同样为这些方法准备了对应的函数，代码如 LIST 15.54 所示。

LIST 15.54　requests_other_methods.py

# coding: utf-8
import requests
def main():
  requests.put('http://127.0.0.1:5000/put', {'foo': 'bar'})  # PUT
  requests.delete('http://127.0.0.1:5000/delete')  # DELETE
  requests.head('http://127.0.0.1:5000/get')  # HEAD
  requests.options('http://127.0.0.1:5000/options')  # OPTIONS
if __name__ == '__main__':
  main()

执行了这段代码之后，程序会向服务器发送 HTTP 的 PUT、DELETE、HEAD、OPTIONS 方法的请求，获取响应后执行结束。

可见，用 Requests 可以轻松使用以 HTTP 为接口的 REST API。