RESTful API 调用详解（零基础友好版）

RESTful API 调用是互联网时代不同程序之间 "沟通" 的通用语言，手机 APP、网页、后端服务的数据交互几乎都离不开它。

一、先搞懂 2 个核心概念（类比帮你秒懂）

1. 什么是 API？

API 的全称是 Application Programming Interface （应用程序编程接口），可以理解成 "程序之间的服务员"。

举个生活例子：你去餐厅吃饭，不用直接进厨房做饭，而是通过服务员下单 → 服务员把需求传给厨师 → 厨师做好后，服务员再把菜端给你。

在程序世界里：

你（用户） → 手机 APP / 网页（客户端）
服务员 → API
厨师 → 后端服务器 / 数据库
菜 → 你需要的数据（比如天气信息、商品列表）

简单说：API 就是客户端和服务器之间的 "桥梁"，负责传递请求和响应。

2. 什么是 RESTful API？

REST 是 Representational State Transfer （表述性状态转移）的缩写，它不是一个协议，而是一套API 设计的风格和规范。

遵循这套规范设计的 API，就叫 RESTful API 。它的核心特点是 "简洁、通用、易理解"，就像全世界通用的 "普通话"，不管是 Java、Python 还是前端 JS 写的程序，都能看懂。

二、 RESTful API 的核心设计原则（必须记住）

RESTful API 的设计围绕 **"资源"** 展开，资源可以是任何数据（用户、订单、商品）。核心原则有 5 个：

资源为中心，URL 只描述资源
- URL（网址）只用来表示 "资源是什么"，不包含 "对资源的操作"。
- 错误示例：/getUser（URL 里带了操作get）
- 正确示例：/users（直接描述资源 "用户"）
用 HTTP 方法描述对资源的操作
- 操作资源的动作（增删改查），通过 HTTP 的 4 个核心方法来表示，不用在 URL 里写。| HTTP 方法 | 对应操作 | 通俗理解 | 示例 URL ||---|---|---|---|| GET | 查询资源 | 读取 / 获取数据 | GET /users（获取所有用户） || POST | 创建资源 | 新增数据 | POST /users（创建新用户） || PUT | 更新资源 | 全量修改数据 | PUT /users/1（修改 ID=1 的用户） || DELETE | 删除资源 | 删除数据 | DELETE /users/1（删除 ID=1 的用户） |
无状态通信
- 服务器不保存客户端的任何状态，每次请求都必须包含所有必要信息（比如身份认证的 token）。
- 好处：服务器不用记录历史请求，更容易扩展。
响应格式统一（推荐 JSON）
- 服务器返回的数据格式通常是 JSON（轻量级、易解析），少数情况用 XML。
- 示例 JSON 响应（获取用户 ID=1 的结果）： json
  复制代码
```
{
    "code": 200,
    "msg": "success",
    "data": {
        "id": 1,
        "name": "张三",
        "age": 20
    }
}
```
使用 HTTP 状态码表示请求结果
- 服务器用HTTP 状态码 告诉客户端请求是否成功，不用在响应体里自定义 "成功标识"（虽然很多项目会加）。| 状态码 | 含义 | 常见场景 ||---|---|---|| 200 | OK | 请求成功（比如 GET 查询成功） || 201 | Created | 创建成功（比如 POST 新增用户成功） || 400 | Bad Request | 请求参数错误 || 404 | Not Found | 请求的资源不存在（比如/users/999不存在） || 500 | Internal Server Error | 服务器内部错误 |

三、 RESTful API 调用的完整流程（一步不差）

调用一个 RESTful API，就像 "客户端给服务器发一封有格式的信"，流程分为4 步：

构造请求：客户端组装请求的 3 个核心部分
- 请求方法：比如 GET/POST
- 请求 URL ：比如https://api.example.com/users
- 请求参数 / 请求体 ：
  - GET 请求：参数拼在 URL 后面，比如/users?age=20（查询年龄 20 的用户）
  - POST/PUT 请求：参数放在请求体里（通常是 JSON 格式）
- 可选：请求头 （比如Content-Type: application/json，告诉服务器 "我发的是 JSON 数据"）
发送请求：客户端通过网络把请求发给服务器
服务器处理：服务器接收请求，执行对应的操作（查数据库 / 写数据）
接收响应：服务器返回响应数据，包含 3 部分
- 状态码：比如 200/404
- 响应头 ：比如Content-Type: application/json
- 响应体：实际的数据（比如用户列表的 JSON）

四、零基础能上手的 Python 代码实现

我们用 Python 最常用的requests库来调用 RESTful API，这个库语法简单，适合新手。步骤 1 ：先安装requests库（打开命令行执行）

bash

运行

复制代码

pip install requests

步骤 2 ：调用免费的测试 API（JSONPlaceholder）JSONPlaceholder 是一个提供模拟 RESTful API 的免费网站，不用注册，直接调用。我们以用户资源 为例，实现查、增、改、删4 个操作，代码逐行加中文注释。

python

代码运行结果说明

JSONPlaceholder 是模拟 API，创建 / 修改 / 删除操作不会真正改变它的数据库，但会返回正确的状态码和响应数据，适合新手练习。
实际项目中，你需要替换成真实的 API 地址（比如公司后端提供的https://api.xxx.com/users）。

五、新手常见误区与注意事项

混淆 HTTP 方法的用途
- 不要用 GET 请求创建 / 修改数据（GET 请求的参数会暴露在 URL 里，不安全）。
- 不要用 POST 请求查询数据（违反 RESTful 规范，可读性差）。
忘记设置请求头
- 发送 JSON 数据时，一定要确保请求头包含 Content-Type: application/json，否则服务器无法解析。
- requests库的json参数会自动设置这个请求头，不用手动加。
忽略状态码的含义
- 不要只看响应体的数据，一定要先判断状态码是否成功（比如 200/201）。
- 遇到 404 错误，先检查 URL 是否写错；遇到 500 错误，大概率是服务器的问题。
API 认证问题
- 很多真实 API 需要身份认证（比如 token），需要在请求头里添加 Authorization: Bearer <你的token>。
- 示例： python
  
  运行
  复制代码
```
headers = {"Authorization": "Bearer your_token_here"}
response = requests.get(BASE_URL, headers=headers)
```

六、总结

RESTful API 调用的核心就是 "用正确的 HTTP 方法，访问正确的 URL，传递正确的参数，解析正确的响应"。对于零基础学生，记住以下 3 点就能快速上手：

URL 描述资源，HTTP 方法描述操作；
常用方法：GET 查、POST 增、PUT 改、DELETE 删；
Python 用requests库调用，核心步骤是发请求→判状态码→解析 JSON。