API 入门：从零理解"程序之间的对话"

🎯 核心问题

什么是 API? 这就像问:餐厅的菜单怎么设计,客人一看就懂?服务员怎么记单,不会出错?API 解决的就是"程序之间如何对话"的问题。你写代码的第一天就在用 API,只是你可能没意识到。

0. 新手常见的三个困惑

困惑一:API 是很高深的东西吗?

很多人一听到 API,就觉得是高级工程师才能理解的概念。其实你早就用过 API 了:

python

len("hello")        # 这就是 Python 提供的 API
open("file.txt")    # 这也是 API
requests.get(url)   # 这还是 API

困惑二:Web API 和普通 API 有什么区别?

类型	调用对象	通信方式	典型场景
函数 API	本地代码	函数调用	`len()`, `open()`
操作系统 API	操作系统	系统调用	读写文件、创建进程
Web API	远程服务器	HTTP 请求	调用 AI 模型、获取天气

困惑三:我该用 HTTP 还是 SDK?

python

# HTTP 方式:自己处理所有细节
import requests
response = requests.post(
    "https://api.deepseek.com/v1/chat/completions",
    headers={"Authorization": "Bearer sk-xxx"},
    json={"model": "deepseek-chat", "messages": [...]}
)
result = response.json()["choices"][0]["message"]["content"]

# SDK 方式:管家帮你处理
from openai import OpenAI
client = OpenAI(api_key="sk-xxx")
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[...]
)
result = response.choices[0].message.content

1. API 的本质:插头与插座

API(Application Programming Interface,应用程序编程接口)就是"程序之间对话的约定"。

1.1 用电器来类比

概念	电器类比	API 对应
接口	插座形状	函数签名 / URL
输入	电流输入	函数参数 / 请求体
输出	电器工作	返回值 / 响应体

1.2 三种 API 形态对比

调用对象本地代码库

通信方式函数调用

延迟纳秒级

典型场景数据处理、文件操作

函数 API 示例

len("hello")           # 返回 5
max([1, 5, 3])         # 返回 5
open("file.txt").read() # 读取文件

1.3 函数 API vs HTTP API 的区别

很多初学者会困惑：函数 API 和 HTTP API 到底有什么区别？看文档时该如何区分？

📚 函数 API vs HTTP API本地调用 vs 网络请求，文档怎么看？

📦函数 API

调用方式直接函数调用

参数传递括号内传参

返回值直接获得结果

错误处理异常/返回值

Python 示例

# 调用内置函数
length = len("hello")      # 返回 5

# 调用库函数
import math
result = math.sqrt(16)     # 返回 4.0

# 调用自定义函数
def add(a, b):
    return a + b
sum = add(3, 5)            # 返回 8

🌐HTTP API

调用方式网络请求

参数传递URL/Body/Header

返回值JSON/XML 响应

错误处理状态码判断

HTTP 请求示例

POST /v1/chat/completions HTTP/1.1
Host: api.deepseek.com
Authorization: Bearer sk-xxx
Content-Type: application/json

{
  "model": "deepseek-chat",
  "messages": [
    {"role": "user", "content": "你好"}
  ]
}

核心要点：函数 API 是"本地办事"，HTTP API 是"远程通信"。看文档时，函数关注参数和返回值，HTTP API 关注 Endpoint、认证和请求/响应格式。

1.4 不同类型的 API 文档怎么看

面对不同类型的 API 文档，关注重点各不相同：

📋 不同文档类型怎么看函数文档、REST API 文档、SDK 文档，各有侧重点

文档类型函数文档

适用场景使用标准库/第三方库函数

阅读难度⭐⭐

🔍 看文档时重点关注

函数签名参数类型返回值异常说明示例代码

📝文档示例

### json.loads(s, *, cls=None, object_hook=None...)

将 JSON 字符串解析为 Python 对象

**参数：**
- s (str): 要解析的 JSON 字符串
- cls (JSONDecoder): 自定义解码器类
- object_hook (callable): 可选的转换函数

**返回值：**
- dict | list: 解析后的 Python 对象

**异常：**
- JSONDecodeError: 字符串格式非法

**示例：**
>>> import json
>>> json.loads('{"name": "Alice"}')
{'name': 'Alice'}

💡阅读技巧

先看函数签名，了解需要什么参数
注意参数的类型和是否必填
查看返回值类型，方便后续处理
关注可能抛出的异常，做好错误处理

📊三种文档快速对比

对比项

函数文档

REST API 文档

SDK 文档

核心关注

参数、返回值

Endpoint、请求体

初始化、方法链

代码示例

函数调用

HTTP 请求

对象方法

错误处理

异常/返回值

状态码

异常对象

先看什么

函数签名

Base URL + Auth

Quick Start

阅读建议：函数文档看签名，API 文档看请求格式，SDK 文档看示例。遇到不会的，先找「Quick Start」或「Getting Started」章节。

2. 一次完整的 API 调用

👇 动手试试看:点击下方按钮,观察一次完整的 API 请求-响应流程:

API 请求演示

// 点击下方按钮，模拟不同的 API 请求

> ▋

💻客户端发起请求

等待请求...

HTTP Request→

🖥️服务器处理请求

等待中...

HTTP Response←

📦响应返回结果

等待响应...

💡 点击命令按钮，观察一次完整的 API 请求-响应流程。

2.1 API 调用的四个阶段

阶段	发生了什么	电器类比
请求	客户端向服务器发送请求	按下开关
传输	请求通过网络传输到服务器	电流通过电线
处理	服务器处理请求并返回数据	电器开始工作
响应	客户端接收并处理返回结果	灯泡发光

2.2 餐厅类比

餐厅角色	API 对应	说明
菜单	API 文档	告诉你有哪些"菜"可以点
服务员	HTTP 协议	标准化的"对话方式"
后厨	服务端	按"订单"处理请求
上菜	响应	把结果返回给"客人"

3. HTTP 方法:你是在"问"还是在"做"?

调用 Web API 时,你需要告诉服务器你想做什么。这就是 HTTP 方法的由来。

3.1 用餐厅点餐来理解

场景	现实中你会怎么说?	对应的 HTTP 方法
你想知道今天有什么菜	"服务员,菜单给我看看"	GET - 纯"问",不改数据
你想点一份宫保鸡丁	"给我来份宫保鸡丁"	POST - "做"件事,创建数据
你想换一道菜	"把宫保鸡丁改成糖醋里脊"	PUT - 替换数据
你想改口味	"宫保鸡丁不要放花生"	PATCH - 部分修改
你不想要了	"算了,那道菜不要了"	DELETE - 删除数据

get

获取

查询数据

幂等

post

创建

新增数据

不幂等

put

全量更新

替换资源

幂等

patch

部分更新

修改字段

不幂等

delete

删除

删除资源

幂等

get获取 - 查询数据

从服务器获取资源,不会修改任何数据

餐厅类比:"服务员,菜单给我看看"

GET /api/users           # 获取用户列表
GET /api/users/123       # 获取单个用户
GET /api/products?cat=phone  # 查询手机商品

关于幂等性

幂等性:多次执行结果是否相同?

幂等的操作(GET/PUT/DELETE):点 10 次和点 1 次,结果一样
不幂等的操作(POST):点 10 次,可能创建 10 个订单

解决方案:POST 操作用唯一 ID 校验,避免重复处理。

3.2 HTTP 方法速查表

方法	用途	幂等性	安全性	典型场景
GET	获取资源	是	是	查询列表、查看详情
POST	创建资源	否	否	新增用户、提交订单
PUT	全量更新	是	否	替换整个用户资料
PATCH	部分更新	否	否	只修改昵称
DELETE	删除资源	是	否	删除用户、取消订单

4. HTTP 状态码:服务器在告诉你什么?

服务器回复时,会先返回一个状态码,告诉你请求是否成功。

4.1 状态码分类

2xx成功

请求被成功接收、理解并处理

200 OK201 Created204 No Content

3xx重定向

需要进一步操作才能完成请求

301 永久移动304 未修改307 临时重定向

4xx客户端错误

请求包含错误或无法完成

400 参数错误401 未认证403 无权限404 不存在

5xx服务器错误

服务器无法处理有效请求

500 内部错误502 网关错误503 服务不可用

💡记忆技巧:2️⃣ 成功 • 3️⃣ 重定向 • 4️⃣ 客户端错 • 5️⃣ 服务器错

4.2 常见状态码详解

状态码	含义	典型场景	客户端处理
200 OK	成功	请求正常处理	展示数据
201 Created	创建成功	POST 请求成功创建资源	跳转到新资源
400 Bad Request	请求格式错误	参数缺失或格式不对	检查参数
401 Unauthorized	未认证	没有提供有效的 API Key	引导用户登录
403 Forbidden	无权限	API Key 没有访问该资源的权限	提示权限不足
404 Not Found	不存在	请求的地址或资源不存在	检查 URL
429 Too Many Requests	请求过多	超过了速率限制	稍后重试
500 Internal Server Error	服务器错误	服务端出了问题	提示用户稍后重试

👇 动手试试看:点击下方按钮,了解常见状态码的含义:

HTTP 状态码演示

// 点击按钮查看不同状态码的含义

> ▋

✅2xx 成功

200OK请求成功

201Created创建成功

204No Content成功但无返回内容

⚠️4xx 客户端错误

400Bad Request请求格式错误

401Unauthorized未认证

403Forbidden无权限

404Not Found资源不存在

422Unprocessable语义错误

429Too Many请求过多

🔴5xx 服务端错误

500Server Error服务器内部错误

502Bad Gateway网关错误

503Unavailable服务不可用

💡 点击命令按钮，了解常见的 HTTP 状态码。

5. HTTP vs SDK:自己跑腿还是让管家代办?

5.1 两种调用方式对比

	🏃 HTTP API	🤵 SDK
比喻	自己跑腿	管家代办
优点	✓ 所有语言都能用 ✓ 完全控制请求细节 ✓ 无需额外依赖	✓ 代码简洁易读 ✓ 自动处理鉴权 ✓ 内置错误重试
缺点	✗ 需要处理所有细节 ✗ 代码冗长易出错	✗ 需要安装依赖 ✗ 可能有版本问题
代码示例	`requests.post(url, json=..., headers={...})`	`client.chat.completions.create(...)`

5.2 如何选择?

场景	推荐方式	原因
快速开发	SDK	自动处理鉴权、错误、重试
学习原理	HTTP	理解底层机制
不支持的语言	HTTP	任何语言都能用
需要定制	HTTP	灵活控制每个细节

💡 建议

能用 SDK 就用 SDK,把麻烦事留给库,把时间留给自己。

6. 如何阅读 API 文档?

API 文档就像说明书和菜单的结合体。你不需要从头读到尾,只需要学会"查字典"。

6.1 文档阅读清单

打开任何一个 API 文档(比如 OpenAI 或 DeepSeek),你只需要找这几样东西:

📖API 文档翻译机

Base URL

https://api.deepseek.com

Endpoint

POST /v1/chat/completions

Headers

Authorization: Bearer sk-xxx
Content-Type: application/json

Body 参数

model必填模型名称

messages必填对话消息

temperature可选0-2，默认1

翻译成代码

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxx",
    base_url="https://api.deepseek.com"
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "你好"}]
)

核心思想：看文档找三样：地址（Base URL）、鉴权（Authorization）、参数（Parameters）。

项目	说明	示例
Base URL	API 的根地址	`https://api.deepseek.com`
Authentication	如何证明身份	`Authorization: Bearer sk-xxx`
Endpoints	具体的接口列表	`/v1/chat/completions`
Parameters	必填/可选参数	`model`(必填)、`temperature`(可选)
Response	返回数据结构	`{"choices": [...]}`

6.2 阅读文档的步骤

找到 Base URL - 这是所有请求的前缀
看懂认证方式 - API Key 放在 Header 还是 Query?
找到需要的 Endpoint - 你要调用的具体接口
查看请求参数 - 哪些必填?哪些可选?
理解返回格式 - 数据是如何组织的?

7. 动手练习:模拟 API 调用

光说不练假把式。这里有个模拟 API,你可以随便填参数、随便改地址,看看会发生什么。

🧪API 练手场随便玩，坏了算我的

Endpoint

方法

API Key

点击发送查看结果

快速尝试：

试着触发以下场景:

✅ 成功请求:填入正确的 Endpoint 和 API Key
❌ 401 错误:不填 API Key,看看服务器怎么拒绝你
❌ 404 错误:填一个不存在的地址

8. 小结

核心要点

API 就是传声筒,帮你把话传给另一段代码或远程服务器
你早就用过 API 了,从 len() 到 open() 都是 API
Web API 是超能力,让你调用千里之外的超级电脑
SDK 是好管家,能用 SDK 就别自己跑腿
看文档找三样:地址、鉴权、参数

在 AI 编程的时代,你只需要记住这几个核心概念。剩下的细节,IDE 和 AI 助手会帮你处理。

名词速查表

名词	全称	解释
API	Application Programming Interface	应用程序编程接口,定义了软件之间如何交互
Web API	-	基于 HTTP 协议的 API,用于网络通信
Endpoint	-	端点,API 的具体地址
HTTP	HyperText Transfer Protocol	Web API 使用的通信协议
GET	-	获取资源的方法
POST	-	提交数据的方法
SDK	Software Development Kit	软件开发工具包,封装了底层 API 调用
URL	Uniform Resource Locator	API 的网络地址
JSON	JavaScript Object Notation	常用的数据格式
Authentication	-	验证身份的过程
Status Code	-	HTTP 响应中的状态码
Request	-	请求
Response	-	响应
Header	-	HTTP 头,包含元信息
Payload	-	请求或响应的实际数据
Rate Limit	-	速率限制
Idempotent	-	幂等,多次执行结果相同
REST	Representational State Transfer	一种 API 架构风格
RPC	Remote Procedure Call	远程过程调用
GraphQL	-	一种查询语言 API
gRPC	-	Google 开发的高性能 RPC 框架

API 入门：从零理解"程序之间的对话" ​

0. 新手常见的三个困惑 ​

1. API 的本质:插头与插座 ​

1.1 用电器来类比 ​

1.2 三种 API 形态对比 ​

1.3 函数 API vs HTTP API 的区别 ​

1.4 不同类型的 API 文档怎么看 ​

2. 一次完整的 API 调用 ​

2.1 API 调用的四个阶段 ​

2.2 餐厅类比 ​

3. HTTP 方法:你是在"问"还是在"做"? ​

3.1 用餐厅点餐来理解 ​

3.2 HTTP 方法速查表 ​

4. HTTP 状态码:服务器在告诉你什么? ​

4.1 状态码分类 ​

4.2 常见状态码详解 ​

5. HTTP vs SDK:自己跑腿还是让管家代办? ​

5.1 两种调用方式对比 ​

5.2 如何选择? ​

6. 如何阅读 API 文档? ​

6.1 文档阅读清单 ​

6.2 阅读文档的步骤 ​

7. 动手练习:模拟 API 调用 ​

8. 小结 ​

名词速查表 ​