公共请求约定
统一核对 API 地址、三种认证方式、响应状态及示例占位值。
地址与示例
本文使用 API 基础地址 https://admin.duoge.work/api。私有化部署使用管理员交付的对外 API 地址；路径前缀只拼一次。浏览器 #/… 地址是页面路由，不能作为接口地址。
示例中的 YOUR_APPLICATION_ID、YOUR_FORM_ID、YOUR_RECORD_ID、YOUR_TEXT_COLUMN、YOUR_TEXT_FIELD 均须替换。租户 Header 必须使用数字 ID；CURRENT_MILLISECONDS 必须替换为当前毫秒时间戳，不能发送占位文本。业务数据仅为结构示例，不代表已向线上执行请求。
认证方式不能混用
| 接口 | 认证与上下文 | 请求格式 |
|---|---|---|
| 获取 Token | 租户 Header、openapi 授权表单及签名 | x-www-form-urlencoded |
| 应用信息、应用表单信息 | 用户 Bearer、租户与应用上下文 | GET |
| 直接 V1 / V2 数据接口 | 用户 Bearer、租户、应用、毫秒时间戳、当前请求签名 | JSON |
| V2 菜单中的 Basic 网关 | 客户端 Basic、授权 username、租户与应用 | JSON |
| 匿名分享 | 路径中的分享 Token、按需访问密码 | GET 或 JSON POST |
Access Secret 用于 HMAC 签名；OAuth client_secret 用于客户端认证；用户 Access Token 用于 Bearer；分享 Token 只用于当前分享。四者用途不同。
直接数据接口常用 Header：
Authorization: Bearer YOUR_ACCESS_TOKEN
TENANT-ID: YOUR_NUMERIC_TENANT_ID
X-APPLICATION-ID: YOUR_APPLICATION_ID
app_id: YOUR_APPLICATION_ID
timestamp: CURRENT_MILLISECONDS
signature: SIGNATURE_FOR_THIS_REQUEST
Content-Type: application/json
如果授权提供了 access_id，按部署合同携带，并把实际发送值加入签名参数。重复出现在 Header、query 或 body 的同名值必须一致。签名之后不能再修改请求内容。算法及五种语言示例见生成签名。
响应与错误
普通业务接口采用 code、msg、data 等包装，成功通常为 code=0；Token 响应直接读取 access_token。先检查 HTTP 状态，再检查业务状态，最后解析 data，不仅判断 HTTP 200。
| 结果 | 处理 |
|---|---|
| Token 过期 / 认证失败 | 检查授权主体、客户端和实际 expires_in |
| 签名或时效校验失败 | 检查最终参数字符串、Secret、当前毫秒时间戳和时钟 |
| 无权访问 / 表单不存在 | 核对租户、应用、表单归属及用户权限 |
| 查询为空 | 核对筛选条件和记录权限；空结果不等于接口故障 |
| 写入失败或结果不明确 | 保存业务错误；超时先查询确认，不直接重复新增 |
| 分享失效 | 检查撤销、到期、访问次数、密码与分享类型 |
分页、数组、写入结果对象的 data 结构不同，以具体接口页说明为准。文档中的返回示意仅展示相关字段，实际响应可能包含更多字段。不要假定所有写接口都返回 ids、updatedIds 或 deletedIds。
版本选择
V1 使用 columns.metadata / columns.values 与 conditions；直接 V2 写入使用 app_id、table、data 和记录 id / ids。新语义写入优先采用 V2，V1 用于既有协议兼容。当前目录中的读取接口位于 V1；不能只把 URL 加上 v2 就认为存在对应读取接口。
签名正确不会扩大用户权限，指定列或关联表也不会扩大可见范围。写入前先查询目标，写入后回查；批量操作不作跨行全部回滚承诺。