API、REST、JSON、参数与接口文档
把产品动作翻译成可调用、可验收的接口契约。
- 用自己的话解释“API、REST、JSON、参数与接口文档”及其核心术语。
- 在真实 AI 产品场景中识别何时应该使用本课方法。
- 完成一份可沉淀进“系统关系图、一次 API 调用与基础 SQL 练习”阶段任务的实践产出。
REAL SCENE
先从一个真实场景开始
产品写下“新增搜索接口”，工程师却不知道查询哪些字段、空关键词如何处理、结果怎样分页、无权限内容是否过滤、失败能否重试。API 不是一个技术名词，而是系统之间可以共同开发、测试和演进的契约。
PLAIN EXPLANATION
说人话：它到底是什么？
API 定义一个系统向另一个系统开放的能力。REST 常以资源和 HTTP 方法组织接口，JSON 是常见数据格式。接口文档应说明用途、权限、路径、参数类型与必填规则、成功响应、错误、示例、限流和版本。产品经理需要把用户动作和业务规则翻译成接口可验证的输入输出，并区分缺省、空值、不存在和无权限。
从用户动作到资源
先识别业务资源与状态变化，再设计接口，而不是按页面按钮机械建接口。搜索可能是课程集合的查询，收藏是用户与课程的关系。接口边界应稳定，不泄漏临时页面结构。
- 一个接口有明确业务目的
- 资源命名使用一致领域语言
- 组合页面不等于一个万能接口
参数与 JSON 模型
每个参数写清位置、类型、是否必填、默认值、范围和示例。JSON 中缺少字段、null、空字符串和空数组语义不同；金额、时间、枚举和 ID 需要统一格式。
- 枚举列出允许值与未来兼容
- 时间包含时区或统一为 UTC
- 分页排序定义默认与上限
契约、错误与演进
成功响应只返回调用方真正需要的数据，错误使用稳定结构。新增可选字段通常兼容，删除或改变语义可能破坏客户端；版本策略、弃用通知和契约测试能降低演进风险。
- 示例覆盖正常与边界
- 错误包含定位和恢复信息
- 变更前识别所有调用方
API 围绕稳定业务资源和动作设计，不按页面临时拼接。
输入输出必须明确类型、边界、缺省语义和权限。
接口是可版本化契约，变更要兼容、通知并通过测试。
KEY POINT
这节课最重要的结论
- 为什么重要
- 这决定了听懂工程语言、阅读接口和数据库方案，并判断技术取舍时，团队是否拥有一致、可验证的判断标准。
- 适用边界
- 当问题目标、数据来源或失败成本发生变化时，不要机械套用；先重新确认假设和风险等级。
EXAMPLES
正确案例与常见反例
课程搜索 API 定义 query、priority、stage、cursor、limit 与排序，说明空 query 表示浏览、limit 最大 50；服务端先按用户权限过滤。响应返回 items、nextCursor 和 totalEstimate，错误结构含 code、message、requestId；文档提供正常、零结果、非法筛选和限流示例。
接口名叫 getData，接收任意 JSON，所有字段都是字符串；空值、缺字段和 null 含义不明。响应直接返回数据库整行与内部权限字段，分页没有上限。后端改字段名后未通知前端，生产页面全部解析失败。
“请按课程集合查询建模：query 可选，priority 与 stage 为枚举，cursor 分页且 limit 上限 50。权限过滤在服务端完成；空列表是成功响应，不当作 404。错误结构和弃用策略写入接口文档并加入契约测试。”
HANDS-ON
必做实操任务
本节产出：“系统关系图、一次 API 调用与基础 SQL 练习”阶段任务中的《API、REST、JSON、参数与接口文档》一页实践卡
步骤 1选择一个页面动作，识别背后的资源、状态变化和所需接口。
步骤 2为搜索接口定义路径、方法、权限、参数类型、默认值、范围和示例。
步骤 3编写成功、空结果、参数错误、无权限和限流五种 JSON 响应。
步骤 4模拟删除或重命名响应字段，列出调用方、兼容方案和弃用步骤。
核心重点必须完成全部实践，并在测验中达到 80%，才能标记为掌握。
接口目的与用户动作：____
资源：____ 路径：____ 方法：____
调用方与权限：____
参数｜位置｜类型｜必填｜默认｜范围/枚举｜空值语义：
1. ____
2. ____
3. ____
成功状态：____
成功 JSON 示例：____
空结果：____
业务错误码｜HTTP 状态｜恢复：____
分页/排序/限流：____
幂等：____
兼容性与弃用策略：____
契约测试：____CHECKLIST
产品经理工作检查表
MASTERY QUIZ
掌握测验
核心重点需达到 80% 才算掌握，未通过会进入错题本。
INTERVIEW
常见面试题
展开参考回答
从用户动作识别业务资源、状态变化与权限，确定路径和方法；逐一描述参数位置、类型、必填、默认、边界、空值及示例；定义成功、空状态和错误结构，再补分页、排序、限流、幂等、版本兼容与契约测试。最后用正常和异常场景与前后端、测试共同评审。
RECAP & FURTHER READING
重点回顾、延伸阅读与下一步
- 1
围绕“API、REST、JSON、参数与接口文档”继续阅读：查阅对应技术的官方入门文档，重点核对输入输出、失败方式、权限边界与可观测性。
- 2
用“REST、JSON、API 契约”作为检索词，分别写下一条定义、一条适用边界和一个反例。
- 3
对照本课正确案例与反例，寻找一个公开案例并记录其中可复用的判断与不能照搬的条件。