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、驗證碼或完整使用者資料。需要功能指引可使用本頁的“詢問文件”。