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 應原樣使用並綁定在請求脈絡裡，改變篩選條件後要重新分頁。cursor 為 null 表示這次回應已經沒有後續頁了，不代表之後新增的記錄也已經拿到。

不要一律自動重試

GET 請求可以在適當的退避後重試，但驗證碼請求、驗證、會話刷新、分享票據和公開票據都帶有副作用。分享票據的重試可能再次消耗次數，refresh token 的重複使用可能觸發會話撤銷。

上傳意圖使用 Idempotency-Key：同一次操作的重試要保留原本的鍵和完全相同的參數；不同操作則要換新鍵。不要把冪等性概念泛化套用到所有 POST 請求上。請求結果不確定時，先查詢目前狀態再決定是否重試，重試策略應按各介面的定義來處理。

狀態碼與報告

400 檢查參數，401 檢查身份或 grant，403 檢查管理員權限，404 可能是刻意隱藏不可存取的資源，409 是狀態或唯一性衝突，413 是上傳體積邊界，429 是限流，503 是依賴暫時不可用。各狀態碼的詳細含義以對應的功能頁為準。

回報問題時，提供方法、去掉憑據後的路徑樣式、狀態碼和時間即可。不要附上 Authorization、Cookie、分享 token、驗證碼或完整的使用者資料。需要功能指引時，可以使用本站的「詢問文件」功能。