精通 Python API：构建与使用 API 的全面指南

API（应用程序编程接口）可以说是现代软件开发中的英雄。它们让不同的软件系统能够相互通信，从而实现服务集成并构建应用。掌握 API 是任何希望在 Python 中处理数据的人（尤其是开发者）都需要的重要技能。学会这项技能后，您可以构建 Web 应用、连接外部服务，甚至在机器学习项目中使用实时数据，您可能会因此开启新的可能性。

在本指南中，我们将探索 API 的世界，学习如何在 Python 中使用它们、如何使用 FastAPI 构建自己的 API，以及如何应对常见挑战。完成本教程后，您将扎实掌握在项目中使用 API 的方法，使开发过程更高效、应用更强大。如果信息一下子太多，您也可以学习我们的 Introduction to APIs in Python 课程，其中对每个部分都有详细讲解。

What is an API?

API 就像不同软件应用之间的一座桥梁。 它让这些应用能够相互通信并共享信息。

把 API 想象成餐厅里的服务员。您告诉服务员想吃什么（点单），服务员把您的需求传达给后厨。后厨准备好食物，服务员再端回来。同理，您向 API 发送请求，它处理您的请求并返回结果。

为了更具体一些，来看几个真实用例：例如，您可以使用公共 API 获取金融数据进行股票市场分析，或获取实时天气数据以用于气候预测模型。可以看出，API 尤其适用于处理大型数据集和/或满足实时数据需求；否则，集成可能并不会那么棘手。

Python API 的工作原理。图片来源 Napkin.AI

Using APIs in Python

在 Python 中使用 API，是与外部服务交互、获取数据并将各种功能集成到应用中的强大方式。Python 通过 requests 库让 API 使用变得简单高效，该库允许您发送 HTTP 请求与 API 交互。

Introduction to APIs in Python

在 Python 中，多亏了 requests 库，与 API 交互的过程相当直接。该库简化了发送 HTTP 请求的流程，使您能够与 API 通信并获取或发送数据。

Making API requests in Python

在 Python 中开始发起 API 请求之前，您需要安装 requests 库。可使用以下命令安装：

pip install requests技术支持

API 请求基础

让我们把餐厅的概念类比与 Python 中的实际过程结合起来。简化步骤如下：

1. 找到正确的位置： 确定 API 端点，即您将发送请求的特定网址。

2. 下单： 使用 Python 的 requests 库向 API 发送请求。您需要指定要执行的操作类型（如获取数据或发送数据）。

3. 取餐： API 将返回响应，您可以对其进行处理以提取所需信息。

GET requests

GET 请求是最常见的 HTTP 请求类型，用于从服务器检索数据，类似于索取信息；当您在浏览器中输入 URL 并按下回车时，本质上就是向该服务器发送了一个 GET 请求，指定所需资源，服务器会处理请求、查找并准备数据，然后以 JSON 或 XML 等格式返回。

import requestsresponse = requests.get('https://api.example.com/data')data = response.json()print(data)技术支持

在此示例中，我们向一个虚构的 API 发送 GET 请求并打印 JSON 响应。GET 请求通常用于在不修改数据的情况下获取数据。

POST requests

与 GET 请求用于检索数据不同，POST 请求会向服务器发送指令。它们常用于创建新资源（如添加用户）或更新现有资源（如编辑资料）。

想象您正在填写一个在线注册表单。点击提交时，本质上就是携带您的信息发送一个 POST 请求。 下面是一个简化示例：

# Data to send (like user information)data = {'name': 'John Doe', 'email': '[email protected]'}# Send the data to the API (replace the URL with the actual API endpoint)response = requests.post('https://api.example.com/users', json=data)# Check if the request was successful (usually a status code of 201 for creation)if response.status_code == 201:    print("User created successfully!")else:    print("Error:", response.status_code)技术支持

此示例将包含用户信息的字典作为 JSON 数据发送给 API。随后我们检查响应状态码，以确认用户是否创建成功。

Handling responses

当您发起 API 请求时，服务器会返回一个响应，其中包含两个关键信息：

• 状态码（Status Code）： 一个数字，指示请求是成功还是失败。例如，200 通常表示成功，而 404 表示未找到资源。
• 数据（Data）： 您请求的信息，通常为 JSON 格式，价值内容就在这里。

下面是一个 Python 示例：

response = requests.get('https://api.example.com/data')if response.status_code == 200:    data = response.json()    print(data)   else:    print(f"Request failed with status code {response.status_code}")   技术支持

Understanding Python API Status Codes

API 状态码是服务器返回的标准化响应，用于指示客户端请求的结果。这些代码帮助开发者了解请求是否成功、是否发生错误，或是否需要进一步操作。

Common status codes

• 200 OK：该状态码表示请求成功。例如，当您发起 GET 请求从 API 检索数据时，200 OK 响应意味着数据已正确获取。  

• 404 Not Found：当服务器找不到请求的资源时返回此代码。例如，如果您尝试访问一个不存在的端点，会收到 404 Not Found 错误。

• 500 Internal Server Error：该代码表示服务器端出现问题。这是一个通用错误消息，可能由多种原因引发，例如服务器代码中的缺陷或数据库问题。

Handling different status codes

在 Python 应用中妥善处理 API 状态码，可以确保代码行为可预测并优雅地处理错误。 如果响应为 200，则继续处理返回的数据。 遇到 404 错误时，检查端点 URL 是否正确，必要时实现回退逻辑或告知用户资源不可用。 对于 500 错误，可在短暂延迟后重试或记录错误以供进一步排查。但请避免过度重试，以免给服务器带来压力。

Building Python APIs

使用 Python 构建 API 可以创建强大高效的应用接口。Python 的简洁性与强大库使其成为开发 API 的绝佳选择。

Introduction to FastAPI

既然您已掌握如何使用 API，让我们来看看如何构建自己的 API。FastAPI 是一个用于用 Python 构建 API 的现代、高速（高性能）Web 框架。顾名思义，它旨在易于使用。我喜欢 FastAPI 的一点是它还能自动生成交互式文档。

Setting up FastAPI

开始之前，您需要安装 Python 和其包管理器 pip。随后，安装 FastAPI 和高性能 ASGI 服务器 Uvicorn：

pip install fastapi uvicorn技术支持

旁注：如果您在设置 Python 或 pip 时遇到问题，请查看我们的教程：How to Upgrade Python and Pip in Windows, MacOS, and Linux。

Creating a simple API

我们来构建一个返回简单问候语的 API：

from fastapi import FastAPIapp = FastAPI()@app.get("/")def read_root():    return {"Hello": "World"}技术支持

要启动该 API，执行以下命令：

uvicorn main:app --reload技术支持

该命令会启动 Uvicorn 服务器，在 http://127.0.0.1:8000 提供您的 API。通过浏览器访问该 URL，将会看到响应 {"Hello": "World"}。

Advanced Features of FastAPI

FastAPI 不仅能快速创建简单 API，它还提供了一系列高级特性，适用于复杂且高性能的应用。以下是一些关键能力： 

Query parameters

在 FastAPI 中，借助 Python 的类型注解，添加与处理查询参数十分简单。查询参数是 URL 的一部分，用于向 API 端点传递可选数据，通常用来筛选或修改返回的数据。

添加查询参数

在 FastAPI 中添加查询参数，只需在路径操作函数中将其定义为函数参数。如果参数是可选的，可以给它赋一个默认值，如 None。 例如，假设您有一个从数据库检索条目的端点，您希望允许用户通过搜索词筛选：

app = FastAPI()@app.get("/items/")def read_items(q: str = None):    if q:        return {"items": ["Item 1", "Item 2", "Item 3"], "query": q}    return {"items": ["Item 1", "Item 2", "Item 3"]}技术支持

在此示例中，q 是可选查询参数。如果提供了 q 的值，将基于该查询筛选结果；如果未提供，端点将返回所有条目。

处理查询参数

FastAPI 会自动处理查询参数，包括类型校验与转换。例如，如果您将某个查询参数声明为整数，FastAPI 会验证输入确为整数；若不匹配预期类型，FastAPI 会返回清晰的错误信息。

下面是一个包含必填路径参数与类型校验的示例：

@app.get("/items/{item_id}")def read_item(item_id: int, q: str = None):    return {"item_id": item_id, "query": q}技术支持

在这里，item_id 是路径参数，q 是可选查询参数。FastAPI 将确保 item_id 为整数，并在提供时处理查询参数 q。

Handling different HTTP methods

实现 GET、POST、PUT、DELETE 等不同 HTTP 方法很简单，其定义方式与其他框架中定义路由类似。每种方法对应特定操作类型，例如获取数据（GET）、创建数据（POST）、更新现有数据（PUT）或删除数据（DELETE）。

GET 方法

GET 方法用于从服务器检索数据。在 FastAPI 中，您可以这样定义一个 GET 端点：

@app.get("/items/")def get_items():    return {"items": ["Item 1", "Item 2", "Item 3"]}技术支持

POST 方法

POST 方法用于创建新数据。您可以定义一个 POST 端点，并在请求体中接收数据：

@app.post("/items/")def create_item(item: dict):    return {"item": item}技术支持

PUT 方法

PUT 方法用于更新现有数据。通常需要标识符和新数据：

@app.put("/items/{item_id}")def update_item(item_id: int, item: dict):    return {"item_id": item_id, "updated_item": item}技术支持

DELETE 方法

DELETE 方法用于删除数据。在 FastAPI 中，DELETE 端点的定义如下：

@app.delete("/items/{item_id}")def delete_item(item_id: int):    return {"message": f"Item {item_id} deleted"}技术支持

Authentication and security

FastAPI 提供多种机制来实现认证与安全：

• HTTP Basic Auth：一种简单方法，但由于安全性问题，通常不建议在生产环境中使用。
• API Keys：更安全的选项，为客户端生成唯一密钥。
• OAuth 2.0：一种复杂但健壮的授权标准，常用于第三方集成。
• JSON Web Tokens (JWT)：一种在两方之间安全表示声明的流行方法。