API 使用约定

入口与凭据类型

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

| 请求类型 | 认证方式 | | --- | --- | | 申请验证码、验证验证码、公开目录、分享/公开票据 | 按各接口的挑战、口令和可用性检查；不需要登录 token | | 个人文件、配额、分享管理、发布管理 | Authorization: Bearer <accessToken> | | 管理用户、看板、通知 | Bearer 身份并通过服务端 admin 检查 | | 上传分片和完成 | Core 签发的 uploadGrant | | 对象下载 | Core 签发的单次 downloadGrant | | 刷新与退出 | 同源 refresh cookie；不是把 refresh token 放进请求体 |

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、验证码或完整用户数据。需要功能指引可使用本页的“询问文档”。