API 学习目录

知识库简介

API（Application Programming Interface，应用程序编程接口）是程序之间约定好的交互边界。本知识库以最常见的 HTTP API 为主线：先读懂请求与响应，再学 Requests 客户端、认证、分页、限流和可靠性，最后完成一个能自动分页、有限重试并区分错误的 Python 客户端。厂商 API 笔记与长篇 Requests Quickstart 保留为参考层；第一次学习不应从某家 SDK 的参数开始。

资料时点

本目录的通用 HTTP/Requests 资料最后核对于 2026-07-22。RFC 的协议语义相对稳定；厂商 SDK、模型名和端点则以各厂商页自己的 source_checked 为准，不能把本目录日期当作其运行前核验，使用前仍应查相应官方文档。

在总路线中的位置

API 位于“工程与数学基础”知识域，建议在具备 Python 函数/异常与 JSON 对象/数组能力后学习，并把后续 LLM API、Tool Calling、MCP、RAG 服务连接起来。这里要求的是相应能力，不是必须先完成整门 Python 或 JSON 课程。Agent 本质上经常要调用远程模型、搜索服务、数据库网关或自建工具；只会发出一个成功请求，还不足以支撑可恢复的 Agent 系统。

学习目标

完成本路线后，你应能：

• 用“方法 + URL + headers + body”描述请求，用“状态码 + headers + body”解释响应；
• 使用 Requests 调用 JSON API，并始终设置超时；
• 区分 API key、Basic Auth、Bearer token 和 OAuth 2.0 的使用边界；
• 正确处理分页、429 限流、连接/读取超时、重试与指数退避；
• 判断操作是否适合重试，并用幂等键保护支持该机制的创建操作；
• 将传输错误、HTTP 错误、数据格式错误和业务错误分开处理；
• 在不记录凭据的前提下留下足够的请求标识、耗时和错误线索。

前置知识

• 能运行 Python 文件，理解函数、异常、字典和列表；
• 理解 JSON 对象与数组；
• 会在 PowerShell 7 中创建虚拟环境：

python -m venv .venv  # 在当前练习目录创建隔离环境，避免污染系统 Python 的依赖。
.\.venv\Scripts\Activate.ps1  # 只在当前 PowerShell 会话激活刚创建的虚拟环境。
python -m pip install --upgrade pip  # 用当前解释器对应的 pip 更新安装工具。
python -m pip install requests  # 安装本课程后续示例使用的 HTTP 客户端库。

第一次执行激活脚本若被 PowerShell 执行策略阻止，可在当前进程临时使用 Set-ExecutionPolicy -Scope Process Bypass，不要为了一个项目修改全机策略。

推荐学习顺序

1. HTTP 请求与响应：建立协议心智模型，认识方法、URL、headers、body 和状态码。
2. Requests 客户端、Session 与契约阅读：建立隔离环境，理解 Session、TLS、重定向、OpenAPI 与测试替身。
3. 认证、状态码与凭据安全：学会带凭据请求，并根据响应决定下一步。
4. 分页、限流与配额：完整获取列表，并尊重服务端节奏。
5. 超时、重试、退避与幂等性：只在安全条件下恢复临时故障。
6. 错误分类、日志与排查：让失败可诊断，而不是用一个 except Exception 吞掉。
7. 实战：可靠 API 客户端：在本机 mock API 上完成分页、重试和幂等创建。
8. 练习、自测与掌握标准：独立完成任务并检查是否真正掌握。

厂商 API 参考层

这些笔记适合在掌握通用主线后按项目需要查阅。模型名、SDK 方法和计费规则是动态事实，运行前应再次查看笔记所列官方来源。

• 厂商 AI API 参考目录：先阅读共用的验证边界与凭据安全说明。

• OpenAI API

• Anthropic Claude API

• Google Gemini API

• DeepSeek API

• Qwen API

• Kimi API

• 智谱 GLM API

• Mistral API

• Cohere API

• xAI Grok API

Requests 的上传、cookies、流式下载等扩展用法见 Requests Quickstart 中文学习笔记。它保留来源与完整学习价值，但不与通用主线重复计数。

动手实践入口

• 最小练习集中在各课程末尾；
• 综合项目见 实战：可靠 API 客户端；
• 完整代码位于 API/examples/，只访问本机 127.0.0.1，不需要 API key，也不会产生外部费用。

掌握标准

当你能在不照抄成品的情况下完成以下任务，就可以进入 LLM API 集成：

• 从 API 文档中找出 base URL、endpoint、method、认证、参数、响应 schema 和错误约定；
• 写出带 (connect, read) 超时的 Requests 调用；
• 遇到 401、403、404、409、422、429、500、503 时能说明应检查什么，而非一律重试；
• 写出 cursor 分页循环，设置最大页数并防止重复 cursor；
• 只重试临时故障，尊重 Retry-After，为退避加入上限与 jitter；
• 解释“HTTP 方法幂等”与“业务操作不会重复”的区别；
• 日志中保留 request ID、状态码、耗时和尝试次数，同时隐藏 token 与敏感请求体；
• 通过 API/examples 的 35 项自动化测试，并能区分 29 项可靠客户端行为与 6 项离线文档契约分别证明什么。

本轮验证证据

• Python 3.11.9、Requests 2.33.0 下，35 项测试已实际通过：29 项可靠客户端 unit + loopback integration 测试只访问随机本机端口；另外 6 项仅静态解析 OpenAI 参考页中的 Python 代码和防护合同，不调用厂商 API。
• 项目验证了 timeout 参数传递、传输错误归一化（包括 TLS 身份验证失败不重试）、3xx 禁止自动跟随、204、content type、分页失控、重试耗尽、Retry-After 秒数/日期/非法值/等待预算，以及“服务端已创建但首次响应丢失”的幂等恢复。
• 21 篇 Markdown 中的 138 个 Python fenced code 均通过语法解析；76 个完整路径 wikilink 均指向现有文件。
• Requests Quickstart 仅移动到参考层，移动前后 SHA-256 一致，正文未改写。
• 厂商参考示例只完成官方资料核对和 Python 语法解析；未安装全部 SDK，也未使用真实 key 执行可能计费的网络调用。
• Obsidian 阅读视图尚未自动验证；最终集成阶段还会做全库静态链接检查。

与其他知识库的关系

• Python基础 提供语法、虚拟环境和异常处理；JSON 提供请求体与响应体的数据格式。
• LLM API集成 在本知识库的通用 HTTP 可靠性之上学习厂商 SDK、流式事件、token 用量与模型错误。
• Tool Calling（含 Function Calling） 是“模型决定调用什么工具”，API 是“程序怎样可靠地执行该调用”。
• MCP 在协议层统一工具与上下文暴露，但底层仍可能使用 HTTP 或其他传输。
• 运行监控、LLMOps 与 AI安全 会继续扩展日志、指标、凭据治理和故障恢复。

主要参考资料

• RFC 9110: HTTP Semantics
• RFC 6585: Additional HTTP Status Codes
• RFC 9457: Problem Details for HTTP APIs
• RFC 6750: OAuth 2.0 Bearer Token Usage
• Requests 官方文档
• Python http.server 文档

获取日期：2026-07-22。