先看一件具体的事
你在日程页面输入：“明天下午3点开项目会。”页面随即出现一行字：“创建成功。”
假设这个页面承诺把日程保存到服务器：断开服务器连接后，如果它仍声称“已同步到服务器”，就需要检查结果。支持离线保存的应用可以提示“已保存在本机，等待同步”，两者不是同一种成功。
在这个需要服务器保存日程的例子里，至少有两个程序参与。浏览器里的页面负责接收你的话，服务器负责校验、保存和返回结果。这两个程序不能靠心灵感应。它们需要约定：页面把什么交过去，服务器怎样回答，失败时又说什么。
这份约定就是API。
去掉术语后，API就是两个程序之间一张写清楚了格式和回执的办事单。
十秒演示：别背定义，看它工作
假设页面要读取编号为42的日程，它可以发出这样的请求：
GET /api/events/42 HTTP/1.1
Host: example.com
Authorization: Bearer <access-token>
服务器如果找到这条日程，可以回答：
HTTP/1.1 200 OK
Content-Type: application/json
{"id":42,"title":"项目会"}
如果没有找到，它应回答类似：
HTTP/1.1 404 Not Found
这就是最小实验。请求说明“我想做什么”，响应说明“你要求的事发生了没有”。HTTP规范也把交互描述为客户端发送表达意图的请求，服务器解释请求后返回响应，客户端再根据状态码和内容决定下一步。
知道API这三个字母没有用。你能不能画出这次请求从哪里出发、去了哪里、带了什么、返回了什么？能画出来，才算开始搞清楚。
API连接的不是页面，是能力
模型服务拥有理解文字的能力，飞书拥有日历能力，自己的后端拥有用户和业务数据。API把这些能力开出一个受控制的窗口。
窗口通常规定六件事：
- 去哪里办理，也就是Endpoint。
- 要办什么，是读取、创建、修改还是删除。
- 谁来办理，他有没有权限。
- 要交哪些字段，各字段是什么类型。
- 办成后返回什么。
- 办不成时怎样说明原因。
注意，API没有把两个系统的内部代码焊在一起。调用方只知道窗口规则，不需要知道窗口后面用了Node.js、Java还是一群非常勤快的松鼠。这种分隔让两个系统可以各自修改内部实现，只要对外约定没有被破坏。
拾时里可能发生的接力
按照拾时当前的产品方向，一句自然语言变成真实日程，概念上可能经历：
用户输入一句话
↓
页面请求自己的后端
↓
后端请求模型服务理解意图
↓
后端检查模型给出的字段
↓
用户确认
↓
后端写入日程
↓
需要同步时，再请求飞书日历
这里有三种API关系：页面与自己的后端、后端与模型服务、后端与飞书。它们都叫API，但风险不同。
自己的前后端可以一起修改。第三方模型可能限流、超时或升级。飞书还涉及用户授权和Token失效。名字相同，不代表处理方式相同。
这条链路是根据产品规划画出的模型，不是对拾时当前实现的验收结论。具体路由、返回字段和外部同步仍要查看应用代码与测试。
做个反例：格式正确，事情仍然可能错
假设服务器收到：
{
"action": "delete_event",
"event_id": 42
}
JSON合法，字段也齐全。能删吗？还不能。
服务器至少要问：
42这条日程存在吗？- 它属于当前用户吗？
- 用户真的要求删除吗？
- 请求是否因为网络重试被重复发送？
- 删除失败时，页面会不会仍然显示成功？
API负责把请求交过来，不负责证明请求是对的。权限、业务校验、用户确认和结果核对仍由系统承担。
所以“我们已经接了API”不是完成证明。这句话只说明窗口开了，没说明窗口会不会把别人的包裹交给你。
API Key为什么必须留在服务器
浏览器会把HTML和JavaScript下载到访客设备。写进前端的长期凭据，无论改了多奇怪的变量名，访客最终都能拿到。
把钥匙涂成墙壁的颜色，不等于没有把钥匙挂在门外。
模型服务的API Key、平台应用密钥和数据库凭据应该由后端从服务器环境变量或受控密钥服务读取。前端只向自己的后端提交必要数据。后端再做身份验证、字段检查、限流和第三方调用。
失败不是意外，是协议的一半
只考虑成功路径，相当于设计一把只在晴天能开的伞。真实API必须回答：
- 输入不完整时怎么办？
- 用户没有权限时怎么办？
- 第三方限流时能否稍后重试？
- 网络超时后，刚才的操作到底成功没有？
- 同一个创建请求发了两次，会不会出现两条相同日程？
最后一个问题叫幂等性，但别急着背名字。它的实际意思是：门铃卡了一下响了两次，快递员不应该给你放下两个相同包裹。
对创建日程、付款和发送通知来说，这比接口长得漂亮重要得多。
怎样验证理解
下面这些东西看上去很专业，但不能证明API可靠：
- 路由按REST风格命名。
- 文档里有漂亮的请求示例。
- 所有响应都包装成统一JSON。
- 团队说自己采用“微服务架构”。
把这些外表拿掉，只做一个实验：断网、重复提交、换一个用户、删除不存在的数据。系统还能诚实地返回结果吗？如果不能，那只是搭了一座竹子控制塔，飞机不会来。
你真的搞清楚了吗
不用查资料，试着回答：
- 页面显示“成功”时，什么证据能证明服务器真的完成了操作？
- API、HTTP和后端是同一件事吗？如果不是，各自负责什么？
- 为什么一段合法JSON仍然不能直接执行？
- 网络超时后，为什么不能总是立即重试创建操作？
- 如果不能使用“接口”“协议”“请求”三个词，你会怎样向一个六年级学生解释API？
如果暂时答不出来，可以回到请求和响应的例子，再画一次过程。
我现在知道什么，还不知道什么
我现在能确定：API是一份跨程序的交接约定。可靠性不来自“调用成功”四个字，而来自明确输入、身份、结果、失败方式和后续验证。
截至2026年8月28日的应用验收记录，拾时已验证增量同步、幂等重试和数据层用户隔离；真实飞书授权和日历同步仍待验收。本文使用教学示例说明机制，示例路径不是应用接口文档。
资料与验证范围
- 项目依据：
docs/WEBSITE_VISION.md中拾时的自然语言日程、飞书同步和安全规划。 - 相关内容：《AI为什么需要结构化输出》。
- 底层规范：RFC 9110：HTTP Semantics。
- 发布前待核对：拾时应用代码、接口测试，以及实际使用的模型服务与飞书开放平台官方文档。