跳至主要內容
JSR 主頁|登入

查看目錄

API

JSR 有三個你可以互動的 API

JSR 登錄 API

JSR 登錄 API 用於下載模組（套件中的個別 JS/TS 檔案）、套件版本元資料及套件元資料。

注意：所有對 JSR 註冊表 API 的請求都必須以Accept標題製作，該標題不包含text/html，而且請求不得指定Sec-Fetch-Dest: document 。使用Accept: text/html擷取時，註冊表可能會傳回包含底層資料的已呈現 HTML 頁面。

模組

模組使用瀏覽器import陳述式會發起的標準 HTTP GET 請求來提供服務。模組由https://jsr.dev.org.tw網域在下列 URL 提供服務

https://jsr.dev.org.tw/@<scope>/<package-name>/<version>/<path>

例如，@luca/flag套件 1.0.0 版的/main.ts檔案會在下列 URL 提供服務

https://jsr.dev.org.tw/@luca/flag/1.0.0/main.ts

模組是不變的，所以可以無限期快取。註冊表了解條件式請求，因此當提供If-No-Match或If-Modified-Since標題時，會適當回應304 Not Modified。

套件元資料

套件元資料是指有關整個套件的資訊，例如套件範圍、名稱及版本。套件元資料在下列 URL 作為 JSON 提供服務

https://jsr.dev.org.tw/@<scope>/<package-name>/meta.json

例如，@luca/flag套件的元資料會在下列 URL 提供服務

https://jsr.dev.org.tw/@luca/flag/meta.json

此元資料包含套件已發佈版本的清單。這允許工具發現套件可用的版本，並執行語意版本解析，以確定要使用的最佳版本。

元資料中的每個版本都包含該版本資訊，例如已取消狀態和套件版本的exports欄位。exports欄位已正規化為簡易物件表單。

對於上述@luca/flag套件，元資料看起來像這樣

{
  "scope": "luca",
  "name": "flag",
  "versions": {
    "1.0.0": {
      "yanked": true
    },
    "1.0.1": {}
  }
}

套件版本資訊

套件版本資訊是指特定套件版本相關的資訊。

版本資訊以 JSON 格式提供在以下 URL

https://jsr.dev.org.tw/@<scope>/<package-name>/<version>_meta.json

例如，@luca/flag 套件版本的資訊 1.0.0 會提供在以下 URL

https://jsr.dev.org.tw/@luca/flag/1.0.0_meta.json

此資訊包含有關所要求版本的資訊，例如套件版本中的檔案清單、exports 欄位，以及 moduleGraph1 或 moduleGraph2 欄位，其中包含有關模組圖的資訊，以在下載模組時減少瀑布效應。

針對上述 @luca/flag 套件的版本 1.0.0，其資訊如下所示

{
  "manifest": {
    "/deno.json": {
      "size": 75,
      "checksum": "sha256-98719bf861369684be254b01f1427084dc6d16b506809719122890784542496b"
    },
    "/LICENSE": {
      "size": 1070,
      "checksum": "sha256-c3f0644e8374585b209ea5206ab88055c1c503c202bff5d1f01bb29c07041fbb"
    },
    "/README.md": {
      "size": 279,
      "checksum": "sha256-f544a1489e93e93957d6bd03f069e0db7a9bef4af6eeae46a86b4e3316e598c3"
    },
    "/main.ts": {
      "size": 2989,
      "checksum": "sha256-a41796ceb0be1bca3aa446ddebebcd732492ccb2cdcb8912adbabef3375fafc8"
    }
  },
  "moduleGraph1": {
    "/main.ts": {}
  },
  "exports": {
    ".": "./main.ts"
  }
}

版本資訊欄位不會變動，因此可以永久快取。由於這項不變動性質，yanked 欄位不會包含在版本資訊中。請改從套件資訊中取得撤回狀態。

npm 相容性註冊中心 API

npm 相容性註冊中心 API 用於下載 JSR 套件的 npm 相容 tarball，以及取得 npm 相容的套件資訊。

深入了解 npm 相容性層級。

npm 相容性註冊中心 API 由 https://npm.jsr.io 網域提供。

npm 相容性註冊中心 API 的入口點是套件資訊端點。例如，@luca/flag 套件在 JSR 上的資訊（相容性名稱為 @jsr/luca__flag）會提供在以下 URL

https://npm.jsr.io/@jsr/luca__flag

這會傳回一個 npm 相容的套件資訊物件，其中包含以下欄位

  • name：套件的 npm 相容性名稱。
  • description：套件說明。
  • dist-tags：套件的 latest 版本。
  • versions：版本對應的版本資訊的映射。
  • time：版本對應的發佈時間戳記的映射。

versions 欄位是版本對應的版本資訊的映射。版本資訊是一個 npm 相容的版本資訊物件，其中包含以下欄位

  • name：套件的 npm 相容性名稱。
  • version：套件版本。
  • description：套件說明。
  • dist：套件版本的 dist 欄位。這包含套件版本的 tarball URL，以及 tarball 的檢查總和/完整性雜湊。
  • dependencies：套件版本的 dependencies。

已撤消的版本未包含在 versions 欄位中，也不會從 latest dist-tag 中參照。

注意：npm 相容性登錄 API 提供的資料可能並非總是最新或與 JSR 登錄 API 提供的資料一致。版本可能遺失，或者 latest dist-tag 可能已過時。通常這會在幾分鐘內自行解決。

管理 API

管理 API 用於發布套件、管理您的範圍和擷取帳戶資訊。

管理 API 從 https://api.jsr.io 網域提供。這是一個使用 JSON 進行序列化處理的 REST API。

許多發送至管理 API 的要求需要進行驗證。驗證是使用具備 Bearer 或 githuboidc 令牌的 Authorization 標頭進行的。

驗證令牌

JSR 支援使用三種類型的令牌進行驗證

  • 短暫裝置存取令牌，用於驗證使用者身分。這些令牌由使用者透過互動方式進行驗證，並且只在一段短時間內對某個特定目的有效。

  • 長期個人存取令牌，用於驗證使用者身分。個人存取令牌可能具有到期日，並且可能只授予有限權限。個人存取令牌可以在 JSR 帳戶設定頁面的「令牌」標籤中建立。

  • GitHub Actions OIDC 令牌，用於驗證 GitHub Actions 執行者的身分。這些令牌會從 GitHub Actions 內部建立，並且只在一段短時間內有效。它們只能用於發布套件。

裝置取用權杖和個人取用權杖會在 Authorization 標頭中傳遞，並以 Bearer 作為字首。GitHub Actions OIDC 權杖會在 Authorization 標頭中傳遞，並以 githuboidc 作為字首。

Authorization: Bearer jsrd_5gVEGU852nnRH2opZeP9uZ1UdNXog0fcvP8
Authorization: Bearer jsrp_Kj0yFdcksJqHPm04l5tic2WXVtaLS2292b2
Authorization: githuboidc eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMCJ9.eyJyZXBvIjoibHVjYWNhc29uYXRvL2ZsYWciLCJkaWQiOiAieW91IHJlYWxseSB0aGluayBpIHdhcyBnb2luZyB0byBnaXZlIHlvdSBhIHZhbGlkIHRva2VuPyJ9.ZXlKeVpYQnZJam9pYkhWallXTmhjMjl1WVhSdkwyWnNZV2NpTENKa2FXUWlPaUFpZVc5MU

權限

管理 API 有各種權限可授予權杖。這些權限如下

  • package/publish：只允許發布特定套件，可能在特定版本。
  • all：允許所有動作，但 Token 管理除外。

GitHub Actions OIDC 權杖只支援 package/publish 權限，並明確指定套件和版本。

端點

管理 API 的 OpenAPI 3.0 規格可以在 https://api.jsr.io/.well-known/openapi 取得。

OpenAPI 規格的呈現版本可以在 https://jsr.redoc.ly/ 取得。

使用限制

不應在註冊操作期間使用管理 API。你應避免從管理 API 擷取套件版本清單或套件版本之網域資料。請改用 JSR 註冊 API 或 npm 相容性註冊 API。

管理 API 的目的是供需要代表使用者與註冊互動的工具和服務使用。例如，代表使用者將套件發布至 JSR 的工具，會使用管理 API 來發布套件。

工具應使用 User-Agent 標頭識別自己。User-Agent 標頭應採用下列格式

<tool-name>/<tool-version>; <tool-url>

如果工具行為異常，我們可能會封鎖其使用管理 API。

如果您不確定管理 API 是否適於您的使用案例，請透過 help@jsr.io 與我們聯絡。

在 GitHub 上編輯此頁面