REST API 基础概念

什么是 REST API？

REST（Representational State Transfer）是一种设计风格，不是协议或标准。简单说就是：用 HTTP 协议的方式，让程序之间互相通信。

你每天都在用 REST API——刷朋友圈、查天气、叫外卖，背后都是 REST API 在工作。

核心概念

1. 客户端与服务器

┌─────────────┐         ┌─────────────┐
│   你的 App   │  ────→  │   服务器     │
│  （客户端）   │  ←────  │  （服务端）   │
└─────────────┘         └─────────────┘

• 客户端：发起请求的一方（浏览器、手机 App、脚本）
• 服务器：接收请求并返回数据的一方

2. 端点（Endpoint）

端点就是服务器上的一个具体地址，用来执行某个特定操作。

https://api.example.com/v1/chat/completions
                  └──┬──┘ └─┬─┘ └──┬──────────┘
                     │      │      └─ 具体功能路径
                     │      └─ API 版本
                     └─ 域名

类比：端点就像餐厅里的菜单上的某一道菜。你不需要进厨房看厨师怎么做，只需要说出菜名（端点），服务员（API）就会把菜端给你。

3. HTTP 方法（动词）

最常见的四个方法：

AI API 主要用 POST——你每次跟 AI 对话都是一次「提问」，需要发送数据给服务器。

4. 请求结构

一个完整的 HTTP 请求 = 地址 + 方法 + 请求头 + 请求体

POST /v1/messages HTTP/1.1          ← 方法 + 路径
Host: api.anthropic.com              ← 请求头：发给谁
Content-Type: application/json       ← 请求头：数据格式
Authorization: Bearer sk-ant-...     ← 请求头：身份验证

{
  "model": "claude-sonnet-4-5",      ← 请求体（JSON）
  "messages": [...]
}

通俗比喻：你去餐厅吃饭

• 地址 = 餐厅地址
• 方法 = 你进店后说的第一句话（"帮我点个菜"）
• 请求头 = 你的身份信息（会员卡号）、口味偏好（要辣的）
• 请求体 = 你点的具体菜品（菜单内容）

5. 响应结构

服务器返回的数据也是结构化的：

HTTP/1.1 200 OK                     ← 状态码：成功了
Content-Type: application/json       ← 响应头

{
  "id": "msg_01A...",
  "content": [...],                  ← 响应体（JSON）：实际数据
  "model": "claude-sonnet-4-5"
}

状态码速查：

6. JSON 格式

API 通信几乎都用 JSON（JavaScript Object Notation），是一种纯文本的数据格式。

{
  "name": "张三",
  "age": 25,
  "skills": ["Python", "React"],
  "contact": {
    "email": "zhangsan@example.com",
    "phone": "13800138000"
  }
}

特点：

• 大括号 {} = 对象（类似字典/Map）
• 中括号 [] = 数组（类似列表）
• 双引号 = 字符串的标记
• 逗号 = 分隔不同字段

详细信息参见 JSON 数据结构基础

为什么 AI API 都用 REST？

1. 简单：HTTP 协议被所有编程语言支持
2. 灵活：JSON 格式易读易写，人类可读
3. 生态成熟：有无数工具（Postman、curl、各类 SDK）帮你测试
4. 标准化：只要懂 REST，就能接入任何兼容的服务

常见误区

实战检查清单

调用一个 AI API 时，你需要确认：

• 端点 URL 正确：/v1/messages 还是 /v1/chat/completions
• HTTP 方法正确：AI API 通常用 POST
• 请求头完整：特别是 Content-Type 和 Authorization
• 请求体格式正确：字段名、嵌套结构是否符合文档
• 能正确解析响应：知道数据在哪个字段（如 content、choices[0].message）