核心概念

无论使用哪种库，调用 RESTful API 的基本步骤都是相似的：

1. 确定 API 端点: 你要访问的 URL，https://api.example.com/v1/users。
2. 确定请求方法: 常见的有 GET (获取数据), POST (创建数据), PUT (更新数据), DELETE (删除数据)。
3. 设置请求头: 用于传递元数据，如 Content-Type (告诉服务器你发送的数据格式), Authorization (用于身份验证，如 API Key 或 Token)。
4. 准备请求体: 对于 POST 或 PUT 请求，通常需要发送数据（如 JSON 格式）。
5. 发送请求: 将以上信息打包发送到服务器。
6. 处理响应: 接收服务器返回的数据（通常是 JSON 格式）和状态码（如 200 表示成功，404 表示未找到，401 表示未授权）。
7. 错误处理: 检查响应状态码，处理可能发生的网络错误或 API 错误。

使用 requests 库 (最推荐)

requests 是 Python 中最流行、最简洁的 HTTP 库，它极大地简化了 HTTP 请求的编写过程，是进行 API 调用的首选。

安装 requests

如果你还没有安装，可以通过 pip 安装：

pip install requests

基本使用示例

我们将以一个公开的测试 API JSONPlaceholder 为例。

示例 1：GET 请求 (获取数据)

获取一个 ID 为 1 的用户信息。

import requests
import json # 用于美化打印 JSON
# API 端点
url = "https://jsonplaceholder.typicode.com/users/1"
try:
    # 发送 GET 请求
    response = requests.get(url)
    # 检查请求是否成功 (状态码 200-299)
    response.raise_for_status()  # 如果状态码不是 2xx，则会引发 HTTPError 异常
    # 解析 JSON 响应内容
    user_data = response.json()
    # 打印获取到的数据
    print("成功获取用户信息:")
    print(json.dumps(user_data, indent=4, ensure_ascii=False))
except requests.exceptions.HTTPError as http_err:
    print(f"HTTP 错误发生: {http_err}")
except requests.exceptions.ConnectionError as conn_err:
    print(f"连接错误发生: {conn_err}")
except requests.exceptions.Timeout as timeout_err:
    print(f"请求超时: {timeout_err}")
except requests.exceptions.RequestException as err:
    print(f"发生未知错误: {err}")

示例 2：POST 请求 (创建数据)

创建一个新的用户。

import requests
import json
# API 端点
url = "https://jsonplaceholder.typicode.com/users"
# 要发送的 JSON 数据 (作为 Python 字典)
payload = {
    "name": "John Doe",
    "username": "johndoe",
    "email": "john.doe@example.com",
    "phone": "1-770-736-8031 x56442",
    "website": "johndoe.com"
}
# 设置请求头，告诉服务器我们发送的是 JSON 数据
headers = {
    "Content-Type": "application/json; charset=UTF-8"
}
try:
    # 发送 POST 请求，data 参数会自动序列化为 JSON
    # 也可以使用 json=payload，效果相同
    response = requests.post(url, data=json.dumps(payload), headers=headers)
    # 检查请求是否成功
    response.raise_for_status()
    # 解析服务器返回的创建好的用户数据
    new_user = response.json()
    print("成功创建用户:")
    print(json.dumps(new_user, indent=4, ensure_ascii=False))
except requests.exceptions.RequestException as err:
    print(f"发生错误: {err}")

示例 3：带查询参数的 GET 请求

获取所有用户中 id 小于等于 3 的信息。

import requests
import json
# API 端点
url = "https://jsonplaceholder.typicode.com/users"
# 查询参数，requests 库会自动帮我们拼接到 URL 后面
params = {
    'id_le': 3  # 假设 API 支持 id_le (id less than or equal to) 参数
}
try:
    response = requests.get(url, params=params)
    response.raise_for_status()
    users_data = response.json()
    print(f"成功获取 {len(users_data)} 个用户:")
    print(json.dumps(users_data, indent=4, ensure_ascii=False))
except requests.exceptions.RequestException as err:
    print(f"发生错误: {err}")

示例 4：身份验证 (使用 API Key)

很多 API 需要身份验证，常见的做法是在请求头中添加 API Key。

import requests
import json
# 假设这是你的 API Key
API_KEY = "YOUR_SECRET_API_KEY"
url = "https://api.example.com/v1/data" # 这是一个虚构的 API
headers = {
    "Authorization": f"Bearer {API_KEY}",  # Bearer Token 是一种常见的认证方式
    "Accept": "application/json"
}
try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    data = response.json()
    print("成功获取受保护的数据:")
    print(json.dumps(data, indent=4, ensure_ascii=False))
except requests.exceptions.RequestException as err:
    print(f"发生错误: {err}")

使用 urllib 库 (Python 内置)

urllib 是 Python 的标准库，无需安装，但它比 requests 更底层，代码更繁琐，不推荐用于复杂的 API 调用,但了解其基本用法有助于理解底层原理。

import urllib.request
import json
url = "https://jsonplaceholder.typicode.com/users/1"
# API Key 认证示例
API_KEY = "YOUR_SECRET_API_KEY"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "User-Agent": "MyPythonApp/1.0" # 好的做法是设置 User-Agent
}
# 创建请求对象
req = urllib.request.Request(url, headers=headers, method='GET')
try:
    # 发送请求并获取响应
    with urllib.request.urlopen(req) as response:
        # 读取响应内容
        response_body = response.read()
        # 解码 JSON
        data = json.loads(response_body.decode('utf-8'))
        print("使用 urllib 成功获取数据:")
        print(json.dumps(data, indent=4, ensure_ascii=False'))
except urllib.error.HTTPError as e:
    print(f"HTTP 错误: {e.code} - {e.reason}")
except urllib.error.URLError as e:
    print(f"URL 错误: {e.reason}")
except Exception as e:
    print(f"发生错误: {e}")

使用 httpx 库 (现代异步支持)

httpx 是一个现代化的 HTTP 客户端，设计上与 requests 非常相似，但它最大的优势是支持异步 (async/await)，非常适合在异步应用（如 FastAPI, asyncio）中使用。

安装 httpx

pip install httpx

基本使用示例

httpx 的同步用法和 requests 几乎一样。

import httpx
import json
url = "https://jsonplaceholder.typicode.com/users/1"
# httpx.Client 可以用来管理会话，如 cookies
with httpx.Client() as client:
    try:
        response = client.get(url)
        response.raise_for_status()
        user_data = response.json()
        print("使用 httpx 成功获取数据:")
        print(json.dumps(user_data, indent=4, ensure_ascii=False))
    except httpx.HTTPStatusError as e:
        print(f"HTTP 错误: {e.response.status_code} - {e.request.url}")
    except httpx.RequestError as e:
        print(f"请求错误: {e.request.url} - {e}")

异步使用示例 (httpx 的核心优势)

import httpx
import asyncio
import json
async def fetch_user(user_id: int):
    url = f"https://jsonplaceholder.typicode.com/users/{user_id}"
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url)
            response.raise_for_status()
            return response.json()
        except httpx.RequestError as e:
            print(f"获取用户 {user_id} 失败: {e}")
            return None
async def main():
    # 创建多个任务，并发获取多个用户
    tasks = [fetch_user(i) for i in range(1, 4)]
    users = await asyncio.gather(*tasks)
    print("使用 httpx 异步成功获取数据:")
    for user in users:
        if user:
            print(json.dumps(user, indent=2, ensure_ascii=False))
            print("-" * 20)
# 运行异步主函数
asyncio.run(main())

总结与对比

最佳实践

1. 总是使用 try...except 块: 网络请求是不可靠的，可能会因为各种原因失败（断网、服务器宕机、API 限流等）。
2. 检查响应状态码: 使用 response.raise_for_status() 是一个好习惯，它能自动帮你处理 4xx 和 5xx 的错误。
3. 使用 response.json() 解析响应: 除非你明确知道响应不是 JSON,否则这是最方便的解析方式。
4. 设置合理的超时: 在 requests.get(url, timeout=5) 中设置超时,可以防止你的程序因为服务器无响应而永久挂起。
5. 使用会话 (Session): 如果你需要向同一个主机发送多个请求，使用 requests.Session() 可以复用 TCP 连接，提高性能，并自动处理 cookies。
6. 阅读 API 文档: 每个 API 都有其特定的规则，如认证方式、请求头、参数名称等,务必仔细阅读其官方文档。

对于绝大多数 Python requests 库是调用 RESTful API 的最佳选择，如果你正在构建一个异步应用，httpx 是你的不二之选。