API 使用约定

入口与凭据类型

公共 API 前缀是实例的 /api/v1，准确的请求/响应 schema 由源码中的 docs/openapi.yaml 定义。浏览器从同源 Nginx 访问，不要直接连内部 Core、数据库或 Worker 端口。

grant、access token、refresh cookie 不能互换。客户端只使用 Core 返回的对象标识和授权，不要自行生成 grant 或调用私有完成回调。

一个只读的登录后检查

在你自己的 MyWebDrive 实例页面登录后，可以在受控开发客户端用已有 accessToken 检查文件和额度。下面这个函数不会申请验证码、不修改文件，也不把凭据打印出来；它只接受运行时参数，不会把真实 token 写进源码。

async function inspectMyWebDrive(accessToken) {
  if (typeof accessToken !== 'string' || !accessToken.trim()) {
    throw new Error('An authenticated access token is required');
  }
  const read = async (path) => {
    const response = await fetch(`/api/v1${path}`, {
      headers: { Authorization: `Bearer ${accessToken}` },
      credentials: 'same-origin',
    });
    if (!response.ok) throw new Error(`Request failed: ${response.status}`);
    return response.json();
  };
  const [files, quota] = await Promise.all([
    read('/files?limit=20'),
    read('/quota'),
  ]);
  return {
    files: files.items,
    nextCursor: files.nextCursor,
    availableBytes: BigInt(quota.availableBytes),
  };
}

这是一个浏览器同源示例，不能原样在没有 base URL 的 Node.js 中运行。token 应该由实际认证流程传入，不要要求用户复制 HttpOnly cookie。返回的文件信息也应留在你自己的受控环境里。

参数与分页

fileId、shareId、userId 等资源标识使用接口返回的 UUID。分享 token、publication slug 和 fileId 不是同一种标识。路径段逐个用 encodeURIComponent，查询参数用 URLSearchParams，不要拼接未转义的用户输入。

字节数用十进制字符串，计算用 BigInt。文件、版本和公开目录用 nextCursor 分页，管理员用户和通知列表用页码。cursor 应原样使用且绑定请求上下文，改变筛选条件后重置分页。null cursor 表示本次响应没有后续页了，不代表未来新增的记录也已获取。

不要一律自动重试

GET 请求可以在合适的退避后重试，但验证码请求、验证、会话刷新、分享票据和公开票据都有副作用。尤其分享票据重试可能再次消耗次数，refresh token 重用可能触发会话撤销。

上传意图使用 Idempotency-Key：同一次操作重试时保持原键和完全相同的参数不变；不同操作就换新键。不要把幂等性概念泛化到所有 POST。请求结果不确定时先查询当前状态，重试策略要按接口定义来处理。

状态码与报告

400 检查参数，401 检查身份或 grant，403 检查管理员权限，404 可能是有意隐藏不可访问的资源，409 是状态或唯一性冲突，413 是上传体积边界，429 是限流，503 是依赖暂不可用。详细含义以对应的功能页面为准。

报告问题时附上方法、去掉凭据后的路径形状、状态码和时间。不要提供 Authorization、Cookie、分享 token、验证码或完整用户数据。需要功能指引可以使用本页的"询问文档"。