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

0. 新手常见的三个困惑

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

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

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

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

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

# 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 用电器来类比

1.2 三种 API 形态对比

1.3 函数 API vs HTTP API 的区别

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

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

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

2. 一次完整的 API 调用

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

2.1 API 调用的四个阶段

2.2 餐厅类比

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

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

3.1 用餐厅点餐来理解

3.2 HTTP 方法速查表

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

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

4.1 状态码分类

4.2 常见状态码详解

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

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

5.1 两种调用方式对比

5.2 如何选择?

6. 如何阅读 API 文档?

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

6.1 文档阅读清单

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

6.2 阅读文档的步骤

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

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

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

试着触发以下场景:

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

8. 小结

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

名词速查表