Python API 教程（初学者指南）

作者：shuangbiaoli · 2025-09-07 · 阅读时间：22分钟
## 介绍 在使用和构建 API 方面，Python 应用程序是最受欢迎的选择之一。在 Python 生态系统 […]

文章目录

  1. 介绍
  2. API简介
  3. Python 中的 API 请求入门
  4. API 与查询参数的集成
  5. 解码 API 状态代码

介绍

在使用和构建 API 方面，Python 应用程序是最受欢迎的选择之一。在 Python 生态系统中，许多不同的框架（例如Django和Flask ）允许用户构建广泛的 API 套件。许多人转向 Python请求等主要工具来在 Python 应用程序中使用 API。

如果您访问了此博客，您很可能需要在应用程序中使用 JSON 数据。让我们从基础知识开始，看看 API 究竟是什么。

API简介

您可能知道，API 代表应用程序编程接口。 API 的核心是一组允许不同软件应用程序相互通信的规则。它是不同软件系统之间的桥梁，使它们能够以结构化和安全的方式交互和交换数据。用户可以向API发送请求，API将返回某种类型的响应。

更进一步，您可以将 API 视为数据的邮政服务。与通过邮政服务发送和接收信件和包裹类似，软件应用程序使用 API 来发送和接收数据。 API 定义了正确的地址格式（端点）、允许的邮件类型（请求类型）以及您期望收到的返回内容（响应）。

API 几乎为我们现实世界中数字生活的方方面面提供支持。 API 具有广泛的用途，您每天可能会经历多次（可能是数百或数千次）。以下是一些常见示例：

  1. 数据集成：API 允许不同的数据库或软件服务共享数据。例如，天气应用程序可能使用 API 从中央数据库收集天气数据。
  2. 电子商务：在线商店使用 API 与支付处理器连接，确保交易顺利进行。
  3. 社交媒体集成：许多网站和应用程序使用社交媒体 API 来允许用户使用其社交媒体帐户登录、共享内容或导入其个人资料数据。
  4. 物联网设备：在物联网 (IoT) 中，智能恒温器和健身追踪器使用 API 将数据传输到服务器或其他设备。
  5. 云计算：API 在云服务中至关重要，它允许应用程序访问云资源并执行存储数据或运行计算等任务。

API 在现代软件开发中至关重要，因为它们允许创建灵活的模块化软件系统。通过使用 API，开发人员可以构建现有服务的功能，加快开发过程并实现更复杂的功能。例如，支付处理 API（例如Stripe ）可以允许多家公司处理支付，而无需自己构建此类服务。

Python 中的 API 请求入门

在 Python 代码中使用 API 时，您首先需要弄清楚您将发出什么类型的 API 请求。 API 请求可以有不同的类型，通常称为方法。这些方法每个都有一个与其关联的唯一 HTTP 动词以及基于该动词的特定功能。以下是四种最常见的类型。

  • GET ：检索信息。
  • POST ：发送新数据。
  • PUT ：更新现有数据。
  • 删除：删除数据。

您需要根据您尝试通过 API 完成的操作类型来选择正确的端点和动词。例如，我们可能有一个名为/users端点，它根据请求的类型执行不同的功能。如果发出GET请求，可能会返回用户列表，而如果发出POST请求，可能会根据 API 收到的数据创建一个新用户。

用于发出 API 请求的库

为了实际发出 API 请求，Python 有几个可以使用的库。一些最受欢迎的包括：

  • 要求：以其简单性和易用性而闻名。它是初学者的绝佳选择，并且在行业中广泛使用。
  • HTTPx ：具有异步功能的 HTTP 客户端，与 Requests 类似，但具有异步支持。
  • Urllib ：Python 标准库中提供的一个模块，对于基本操作很有用，但与 Requests 相比不太用户友好。

当比较这三个库并决定使用哪一个时，选择相对容易。本质上，它们三个都适用于我们在本博客中讨论的基本操作。然而，随着事情变得更加复杂，您可能需要更深入地了解差异化因素。下面让我们快速浏览一下这些内容。

  • 请求通常因其简单性和代码的可读性而受到青睐。它支持同步请求，非常适合阻塞 I/O 操作。
  • 另一方面， HTTPx是一个更新的库，支持同步和异步请求，使其成为高性能应用程序的不错选择。
  • Urllib是标准库的一部分，但需要更多代码来完成日常任务，并且不如 Requests 直观，因此在新项目中不太受欢迎。

向您的 Python 项目添加依赖项

决定要使用哪个库后，您需要在 Python 代码中包含依赖项。要使用这些库，您首先需要将它们添加到您的 Python 项目中。

如果您使用Requests ，则可以使用 Python 的包管理器 pip 安装它。为此，请打开命令行或终端并运行：

pip install requests

对于HTTPx ， pip的安装命令是：

pip install httpx

由于urllib是标准库的一部分，因此无需单独安装它。

然后，在代码中，您可以导入和使用已添加到项目中的任何库。例如，如果您使用Requests ，则可以像这样使用它：

import requests



response = requests.get(‘https://api.com/test-service’)```



当然，本博客的其余部分将专门关注如何使用Request库。接下来，让我们更详细地了解如何向 API 发出基本请求。

## 发起我们的初始 API 请求

在向 API 发出请求时查看正在运行的代码是理解上述概念的最简单方法之一。让我们使用 Requests 库演示一个基本的 GET 请求。在下面的示例中，代码查询公共 API，然后处理 API 的响应。

import requests

Replace with the desired API endpoint

url = ‘https://api.example.com/data’response = requests.get(url)# Checking if the request was successful
if response.status_code == 200:# Printing the retrieved data
print(response.json())
else:
print(f"Failed to retrieve data: {response.status_code}")“`

在此示例中，我们向 API 端点发送 GET 请求，通过查看状态代码（如果请求成功，状态代码应为200 ）来检查请求是否成功，然后打印 JSON 响应。接下来，我们将看一个稍微高级的示例，我们可以通过查询参数向 API 提供一些数据。

API 与查询参数的集成

当涉及到开发人员的技能时，查询参数是构建 API 请求的一个基本方面。查询参数附加到 API 请求的 URL 中，用于修改请求的行为。本质上，查询参数充当 API 可用于自定义响应的过滤器或附加指令/数据。

要将查询参数添加到 API 请求，您需要使用查询参数语法，该语法需要一个问号 ( ? )，后跟要添加的查询参数。多个参数由与号 ( & ) 分隔。下面是带有 2 个查询参数的 URL 示例。

https://api.example.com/data?parameter1=value1&parameter2=value2

查询参数的用例

在许多场景中，查询参数对于 API 使用者和开发人员来说都很有用。查询参数的常见用途包括：

  • 过滤数据：根据给定标准检索数据子集。
  • 数据排序：按照指定的顺序对返回的数据进行排序。
  • 分页：限制单个请求中返回的结果数量，通常适用于大型数据集。
  • 搜索：查询数据集以获取特定术语。
  • 配置响应：自定义响应，例如指定格式。

在 Python 中实现查询参数

让我们考虑一个实际示例，其中我们使用 Python 中的 Requests 库发出带有查询参数的 GET 请求。假设我们正在访问一个提供书籍信息的 API，并且我们希望根据作者和出版年份过滤结果。我们可以使用下面的代码来过滤出 JK Rowling 于 1997 年撰写的书籍。

import requests



url = 'https://api.example.com/books'

params = {

    'author': 'J.K. Rowling',

    'year': 1997

}response = requests.get(url, params=params)if response.status_code == 200:

    books = response.json()

    for book in books:

        print(book)

else:

    print(f"Error: {response.status_code}")```



上面的代码逐行完成以下任务：



1. 导入requests库。
2. 定义基本 URL ( https://api.example.com/books )。
3. 创建一个名为params的字典，其中包含author和year所需的查询参数。
4. 将 URL 和字典传递给requests.get()函数。
5. 然后，Requests 库会自动使用查询参数构造正确的 URL 并发送请求。
6. 根据返回的状态和数据处理响应。

这应该可以让您很好地了解如何在一个非常简单的示例中将查询参数与Requests一起使用。当然，根据用例，查询参数可能或多或少复杂。

### 使用查询参数的技巧

现在我们已经介绍了使用查询参数的基础知识，我们可以讨论一些提示和技巧来涵盖一些细微差别。让我们回顾一下下面一些最重要的内容。

- __了解 API__ ：使用任何 API 时，尤其是那些带有查询参数的 API，请务必参阅 [API 文档](https://www.explinks.com/wiki/api-docs/)。通过参考文档，您将了解支持哪些查询参数、它们的格式以及它们的使用方式。
- __测试__：当构建具有多个查询参数的请求时，测试它们以确保它们按预期工作并返回正确的数据。随着请求中使用的查询参数越来越长、越来越复杂，格式化和处理出现问题的可能性就越大。始终确保请求按预期工作，最好使用每种可能的查询参数组合（如果有多个）。
- __处理特殊字符__：如果您不知道，最令人沮丧的事情之一是在查询参数中使用某些字符时可能需要进行编码。例如，空格通常被编码为%20或替换为+ 。根据 [API 期望的编码](https://www.explinks.com/blog/headless-web-publishing)类型，这些值可能会有所不同。最简单的确认方法是查看 API 文档中的示例，了解应该对哪些字符进行编码。
- __默认值__：某些 API 可能具有特定查询参数的默认值。了解这些默认值对于正确解释响应至关重要。
- __安全性__：虽然查询参数对于简单的过滤器和配置来说很方便，但敏感信息永远不应该通过查询参数发送，尤其是在未加密的 HTTP 请求中。创建 API 或使用第三方 API 时，您应该始终注意在查询参数中发送的数据以及它是否被视为敏感数据。

###  现实世界的例子

在继续之前，让我们先介绍最后一个更高级的示例。考虑一个 API，您必须在其中发送项目列表作为查询参数。 API 可能期望格式以逗号分隔，如下所示：

https://api.example.com/items?ids=123,456,789

在 Python 中，您可以按如下方式构造此 API 请求：

item_ids = [‘123’, ‘456’, ‘789’]
params = {
‘ids’: ‘,’.join(item_ids)
}

response = requests.get(‘https://api.example.com/items‘, params=params)

Further processing of the response…“`

这里， ','.join(item_ids)从项目 ID 列表中创建一个字符串，以逗号分隔，适合查询参数。 Python 和其他语言中存在多种方法来轻松创建具有比单值查询字符串更复杂的值的请求。

解码 API 状态代码

正如我们在上面的一些代码中看到的，当您向 API 发出请求时，它会返回一个状态代码。这些状态代码是 HTTP 协议的一部分，并在网络上进行标准化，提供了一种快速了解请求结果的方法。本质上，他们会告诉您您的请求是否成功。特定的状态代码也表示错误；如果发生错误，错误类型将反映在返回的状态码中。

状态代码有多种用途：

  • 反馈：它们通知客户端（您的程序）其请求的结果。
  • 故障排除：当请求未按计划进行时，它们可以帮助识别问题。
  • 控制流程：在编程中，开发者可以根据响应状态码来处理不同的场景。

5 个最常见的 HTTP 状态代码

尽管 100 到 599 之间存在许多不同的 HTTP 状态代码，但有些状态代码的使用频率要高得多。让我们简要概述一下您可能会看到的五种最常见的 HTTP 状态代码。

  1. 200 OK ：这是您想要看到的代码。这意味着您的请求成功，服务器正在发送请求的数据。
  2. 404 Not Found ：您尝试访问的资源不存在。如果您输入错误的 URL 或资源已被删除，则可能会发生这种情况。
  3. 500 内部服务器错误：一般错误消息，指示网站服务器上出现问题。这不是你的错，而是服务器端的问题。
  4. 401 未经授权：当所需的身份验证失败或尚未提供时，会出现此状态代码。
  5. 403 Forbidden ：服务器理解您的请求，但拒绝授权。这可能是由于缺乏访问资源的权限。

处理代码中的状态代码

正如我们之前提到的，拥有状态代码的一个优点是它们可用于通知我们的应用程序应如何处理响应。为了演示如何在 Python 中完成此操作，下面是一个使用 Requests 库处理不同状态代码并相应打印消息的基本示例。

import requests



response = requests.get('https://api.example.com/data')if response.status_code == 200:

    print('Success!')

elif response.status_code == 404:

    print('Resource not found.')

elif response.status_code == 500:

    print('Server error.')

elif response.status_code == 401:

    print('Unauthorized. Authentication required.')

elif response.status_code == 403:

    print('Forbidden. Access denied.')

else:

    print(f'Error: {response.status_code}')```



当然，上面的例子非常简单；它只是将一些内容打印到控制台。但是，这为更高级的逻辑铺平了道路，在这些逻辑中，如果返回500状态代码，应用程序可能会在 5 分钟后重试 API 调用，或者如果服务返回401错误，则提示用户输入某些凭据。

### 了解有关状态代码的更多信息

您可以参考详细的资源和帖子，以更深入地了解状态代码的世界及其含义。在 Moesif，我们创建了可以提供帮助的[全面指南](https://www.explinks.com/blog/ua-develop-open-website-tools-comprehensive-guide)和解释以及包含有关状态代码的大量信息的其他资源。以下是 Moesif 或其他可靠来源的文章链接，供您查看：

1. [Moesif 的 HTTP 状态代码指南](https://www.moesif.com/blog/technical/monitoring/10-Error-Status-Codes-When-Building-APIs-For-The-First-Time-And-How-To-Fix-Them/?utm_campaign=Int-site&utm_source=blog&utm_medium=body-cta&utm_content=Python-API-Tutorial)
2. [有关 HTTP 响应状态代码的 MDN Web 文档](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/?utm_campaign=Int-site&utm_source=blog&utm_medium=body-cta&utm_content=Python-API-Tutorial)
3. [有关 HTTP 状态代码的 REST API 教程](https://www.restapitutorial.com/httpstatuscodes.html/?utm_campaign=Int-site&utm_source=blog&utm_medium=body-cta&utm_content=Python-API-Tutorial)

这些资源将提供有关所有可能的 HTTP 状态代码的更多信息，帮助您在使用 API 时遇到它们时更有效地理解和处理它们。

## 导航 API 文档

API 文档对于开发人员来说至关重要，因为它概述了如何有效地使用 API 并与 [API 集成](https://www.explinks.com/wiki/api-integration/)。好的文档应包括有关 API 端点、请求方法、必要参数和预期响应格式的详细信息。

通常有两种类型的 API 文档：通过 [OpenAPI 规范](https://www.explinks.com/blog/how-businesses-can-benefit-from-openapi-specification/)生成的文档和更典型的手写 API 文档。

对于 [OpenAPI](https://www.explinks.com/blog/wx-safe-and-user-friendly-openapi) 生成的文档，这些文档利用 OpenAPI（以前称为 [Swagger](https://www.explinks.com/wiki/what-is-swagger/)），这是一种机器可读 [API 文件规范](https://www.explinks.com/blog/ua-guidelines-for-developing-apis-building-efficient-and-consistent-interfaces)。它允许生成交互式文档，开发人员可以使用它直接从浏览器理解和[测试 API](https://www.explinks.com/blog/ua-how-to-test-api-using-postman)。 [OpenAPI 生成的](https://www.explinks.com/blog/concepts-about-what-is-openapi)文档通常包括易于导航的界面，其中每个端点的可扩展部分显示所需的参数、请求示例和响应模型。

更典型的 API 文档可能在格式上有所不同，但通常包括详细说明 API 各个方面的综合指南，例如身份验证、端点、参数以及示例请求和响应。

### 了解 API 文档

让我们考虑一个假设的示例来了解如何浏览 API 文档。假设我们正在查看[天气 API](https://www.explinks.com/blog/how-governments-can-utilize-a-weather-api-effectively/) 的文档。 /weather端点的部分可能如下所示：

- __端点__： /weather
- __方法__：获取
- __查询参数__：
  - city （必填）： 城市名称
  - units ：测量单位（ metric或imperial ）
- __响应__：包含天气详细信息的 JSON 对象

根据以上信息，我们可以构造一个API请求。如果我们想要以公制单位获取伦敦的天气数据，我们的请求在 Python 中使用 Requests 库将如下所示：

import requests

base_url = "https://api.exampleweather.com"
endpoint = "/weather"
parameters = {
‘city’: ‘London’,
‘units’: ‘metric’
}response = requests.get(base_url + endpoint, params=parameters)if response.status_code == 200:
print(response.json())
else:
print(f"Error: {response.status_code}")“`

然后，此请求将返回包含伦敦天气详细信息的响应（该响应将被打印出来），或者调用可能返回错误，在这种情况下，我们会将错误记录到屏幕上。

对于更高级的示例，让我们考虑一个必须设置正文字段的POST请求示例。假设我们有一个用于任务管理器的 API。创建新任务的文档如下：

  • 端点： /tasks
  • 方法：邮寄
  • 身体：
    • title （必填）：任务的标题
    • description ：任务的详细描述
  • 响应：包含已创建任务详细信息的 JSON 对象

将其转换为请求：

import requests

import json



base_url = "https://api.exampletaskmanager.com"

endpoint = "/tasks"

task_data = {

    'title': 'Grocery Shopping',

    'description': 'Buy milk, eggs, and bread'

}response = requests.post(base_url + endpoint, data=json.dumps(task_data))if response.status_code == 201:

    print("Task created successfully:", response.json())

else:

    print(f"Error: {response.status_code}")```



 在此 POST 请求中：



1. 我们使用json.dumps将task_data字典转换为 JSON 格式的字符串。
2. requests.post方法发送请求，包括请求正文中的任务数据。
3. 状态代码 201 通常表示资源创建成功。

### API 文档导航提示

尽管 API 文档的形式和大小各不相同，但在使用 API 文档来导航新 API 时，需要记住一些关键部分。

- __从身份验证开始__：检查 API 如何处理身份验证（[API 密钥](https://www.explinks.com/blog/api-key-what-is-an-api-key)、[OAuth](https://www.explinks.com/wiki/oauth/) 等）。如果您没有使用 API 期望的正确身份验证机制，那么您肯定会收到不成功的 API 调用，并且可能会收到401响应代码。
- __了解速率限制__：查找任何提及速率限制的内容，以了解您在给定时间范围内可以发出多少个请求。并非所有 [API 都有速率限制](https://www.explinks.com/blog/best-practices-api-rate-limiting-vs-throttling)，但几乎每个公共 API 都会防止滥用和恶意行为，例如拒绝服务攻击。
- __检查端点和方法__：识别可用端点以及它们支持的 [HTTP 方法](https://www.explinks.com/blog/understanding-http-methods-in-rest-api-development-1)（GET、POST 等）。某些端点可能支持多种方法，因此请根据您的预期结果使用正确的方法。
- __查看请求和响应格式__：了解您需要发送的请求的格式以及您将收到的响应。
- __寻找示例__：好的文档通常包括示例请求和响应，这非常有帮助。大多数时候，您可以使用这些示例来构建您的请求，而无需解析许多文档来查找相同的信息。

## 在 Python 中处理 JSON 数据

如果您使用 RESTful API，您将大量使用 JSON。 JSON（JavaScript 对象表示法）是一种轻量级[数据交换](https://www.explinks.com/blog/api-solutions-in-healthcare-pros-cons)格式，易于人类阅读和编写，也易于机器解析和生成。 JSON 因其简单性和灵活性而流行。它与语言无关，解析器适用于每种编程语言，包括 Python。正因为如此，它已成为 API 的通用数据格式。

JSON 对象是键值对的集合，其中键是字符串，值可以是字符串、数字、布尔值、数组甚至另一个 JSON 对象。下面是 JSON 的示例。

{
"name": "John Doe",
"age": 30,
"isEmployed": true,
"skills": ["Python", "JavaScript", "SQL"]
}

Python 内置了json模块，可用于对 JSON 数据进行编码和解码。使用json库，让我们看一些如何在 Python 中使用 JSON 的示例

###  解析 JSON

称为反序列化，下面是如何将 JSON 字符串转换为 Python 对象的示例。

import json

json_string = ‘{"name": "John Doe", "age": 30, "isEmployed": true}’
python_dict = json.loads(json_string)
print(python_dict)“`

生成 JSON

称为序​​列化，下面是如何将 Python 对象转换为 JSON 字符串的示例。

python_dict = {'name': 'Jane Doe', 'age': 25, 'isEmployed': False}

json_string = json.dumps(python_dict)

print(json_string)

从文件中读取 JSON

有时，您需要将 JSON 从文件读取到 Python 程序中。下面是如何使用json.load函数打开文件并加载 JSON 数据的示例。

with open('data.json', 'r') as file:

      data = json.load(file)

将 JSON 写入文件

相反，您可能还想将 JSON 数据写入文件。下面是如何使用json.dump函数执行此操作的示例。

data = {'name': 'Jane Doe', 'age': 25, 'isEmployed': False}

with open('data.json', 'w') as file:

      json.dump(data, file)

通过 API 使用 JSON

通常，您会收到来自 API 的 JSON 数据作为响应。在这种情况下，您可以使用上述方法来读取和写入 JSON（到 API 请求或文件）。下面的示例说明了如何使用response.json读取 API 中的 JSON 数据，然后将其打印到控制台。

import requests

import json



response = requests.get('https://api.example.com/data')# Assuming the response contains JSON data

if response.status_code == 200:

    data = response.json()# Converts JSON to a Python dictionary

    print(data)

else:

    print(f"Failed to retrieve data: {response.status_code}")```



我们之前介绍过的 Python json模块为更复杂的 JSON 操作提供了广泛的支持和功能，例如解析嵌套的 JSON 数据或处理异常。上面的示例应该涵盖了在 Python 中使用 API 和 JSON 数据时会遇到的许多用例。

## Python API 教程：继续前进

现在我们已经介绍了使用 Python 使用 API 的所有基础知识，您可能还有兴趣构建自己的 API。为此，Moesif 创建了一些广泛的指南，向您展示如何使用[Flask](https://flask.palletsprojects.com/en/3.0.x/)和[Django](https://www.djangoproject.com/) （开发人员用来构建 API 的两个非常流行的 Python 框架）构建 API。

在这些指南中，我们将逐步介绍如何构建您自己的 API，并向您展示如何利用 Moesif 来跟踪 API 使用情况、错误并深入了解用户行为。查看它们以开始使用 Python 创建您自己的 API。

##  结论

我们在本博客中介绍了很多内容，从 API 的基础知识开始，深入研究使用 [Python 发出 API](https://www.explinks.com/blog/sa-creating-python-apis) 请求、处理 JSON 数据、理解查询参数和解码状态代码。到目前为止，您应该牢牢掌握如何在 Python 应用程序中使用 API，这是[当今互联数字世界](https://www.explinks.com/blog/importance-of-api-programming)的一项基本技能。

虽然使用 API 至关重要，但[创建和管理](https://www.explinks.com/blog/ua-linux-python-virtual-environment-comprehensive-guide)您自己的 API 可以将您的项目提升到一个新的水平。无论
热门推荐
一个账号试用1000+ API
助力AI无缝链接物理世界 · 无需多次注册
3000+提示词助力AI大模型
和专业工程师共享工作效率翻倍的秘密

热门API

最新文章