第 1.4 章：REST API 结构

学习时间： 45 分钟

---

1. REST API：空间站架构

想象一个空间站，每个模块都具有：

• 标准对接端口（统一接口）

• 明确的专业分工（居住舱、实验室、存储舱）

• 坐标系统（精确位置）

REST (Representational State Transfer) API 遵循相同的原则：

• 所有资源统一接口

• 组件明确分离

• 通过 URI 进行寻址（空间坐标）

💡 核心思想：

每个资源（行星、火箭、宇航员）都有一个唯一的 URL 地址，并通过 HTTP 方法进行交互。

---

2. 宇宙类比中的 REST 6 大原则

REST 原则	国际空间站 (ISS) 类比	对 API 的意义
统一接口	标准对接端口	所有请求规则一致
无状态 (Stateless)	每条指令自给自足	服务器不存储客户端状态
缓存 (Caching)	本地补给品储备	保存频繁响应
客户端-服务器	明确分离：任务控制中心 ↔ 空间站	组件独立发展
分层系统	中继卫星	代理、负载均衡器
按需代码 (Code on Demand)	为实验下载软件	(可选) 传输脚本

---

3. 资源与 URI：宇宙坐标

API 中的每个对象都是一个具有唯一地址的资源：

https://api.spacexdata.com/v4/    ← 基础 URL
          rockets/            ← 火箭集合
          rockets/5e9d0d95eda69973a809d1ec ← 特定火箭 (按 ID)

宇宙资源示例：

• GET /stars → 星星列表
• GET /stars/sirius → 天狼星数据
• POST /satellites → 发射新卫星
• PUT /missions/artemis → 更新任务

URI 层级结构图：

[基础 URL]
├── /planets          → 行星集合
│   ├── /mars         → “火星”资源
│   └── /venus        → “金星”资源
└── /launches         → 发射集合
    ├── /upcoming     → 子集合
    └── /latest       → 资源

---

4. 通过 HTTP 方法进行 CRUD 操作

操作	HTTP 方法	示例 (空间站)	服务器响应
创建 (Create)	POST	发送新模块	201 Created
读取 (Read)	GET	请求模块数据	200 OK
更新 (Update)	PUT	重新配置模块	200 OK
删除 (Delete)	DELETE	脱离旧模块	204 No Content

⚡ 代码示例 (添加卫星)：

import requests

# 使用模拟资源创建的测试服务
new_post = {
    "title": "New Telescope Launch", # 新望远镜发射
    "body": "Hubble-2 is ready for deployment.", # 赫伯2号已准备好部署。
    "userId": 1
}

# 用于演示请求头的假设性 API 密钥
headers = {
    "Authorization": "Bearer YOUR_DEMO_KEY",
    "Content-Type": "application/json; charset=UTF-8"
}

response = requests.post(
    "https://jsonplaceholder.typicode.com/posts",
    json=new_post,
    headers=headers
)

if response.status_code == 201:
    print("✅ 关于新卫星的帖子已成功创建！")
    print("服务器响应：")
    print(response.json())
else:
    print(f"❌ 错误！状态码: {response.status_code}")

---

5. API 版本控制：空间站的演变

就像国际空间站更新模块一样（“曙光”号模块 → “科学”号模块），API 也会变更版本：

• 在 URL 中：https://api.spacex.com/v4/rockets
• 在请求头中：Accept: application/vnd.spacex-v5+json

为何重要：

• v1：基本功能
• v2：添加了新字段
• v3：响应结构发生变化

⚠️ 提示： 始终在请求中指定版本，否则“对接”可能会失败！

---

6. 超媒体 (HATEOAS)：太空导航

API 响应包含指向相关资源的链接 — 就像空间站地图一样：

{
  "id": "iss",
  "name": "国际空间站",
  "crew": 7,
  "_links": {
    "self": { "href": "/stations/iss" },
    "modules": { "href": "/stations/iss/modules" },
    "schedule": { "href": "/stations/iss/schedule" }
  }
}

---

巩固知识的测验

1. REST 的全称是：

a) Rocket Engine System Transfer b) Representational State Transfer c) Remote Space Technology

2. “无状态”原则意味着：

a) 服务器存储请求历史 b) 每个请求都是自给自足的 c) 数据仅通过 SSL 传输

3. 获取 Falcon Heavy 火箭数据的 URI：

a) POST /rockets/falcon-heavy b) GET /falcon-heavy c) GET /rockets/falcon-heavy

4. 用于完全更新资源的方法：

a) PATCH b) POST c) PUT

5. API 中的 HATEOAS 是指：

a) 指向相关资源的链接系统 b) 加密协议 c) 查询语言

检查

---

🚀 本章总结：

REST API 是一个标准化的网络服务“空间站架构”。请记住：

• 资源 = 对象（火箭、行星）
• URI = 对象坐标
• HTTP 方法 = 控制命令
• 版本 = 空间站现代化升级

准备就绪！ 在下一章中，我们将发射一个“测试探测器”——学习如何通过 Postman 测试 API。

📌 实践： 研究 SpaceX API 的结构，并尝试执行：

GET https://api.spacexdata.com/v4/launches/latest — 请注意 URI 和 JSON 结构！