跳至主要内容
JSR 主页|登录

查看目录

API

JSR 有三个您可以与之交互的 API

JSR 注册表 API

JSR 注册表 API 用于下载模块（包中的单个 JS/TS 文件）、包版本元数据和包元数据。

注意：所有对 JSR 注册表 API 的请求都必须使用不包含 text/html 的 Accept 头，并且请求不能指定 Sec-Fetch-Dest: document。当使用 Accept: text/html 获取时，注册表可能会返回一个包含底层数据渲染版本的 HTML 页面。

模块

模块使用标准的 HTTP GET 请求提供服务，就像浏览器 import 语句会发起的请求一样。模块从 https://jsr.deno.org.cn 域名提供服务，位于以下 URL

https://jsr.deno.org.cn/@<scope>/<package-name>/<version>/<path>

例如，@luca/flag 包版本 1.0.0 的 /main.ts 文件将在以下 URL 提供服务

https://jsr.deno.org.cn/@luca/flag/1.0.0/main.ts

模块是不可变的，因此可以无限期地缓存。注册表理解条件请求，因此在提供 If-No-Match 或 If-Modified-Since 头时，将适当地以 304 Not Modified 响应。

包元数据

包元数据是指关于整个包的信息，例如包范围、名称和版本。包元数据以 JSON 格式提供服务，位于以下 URL

https://jsr.deno.org.cn/@<scope>/<package-name>/meta.json

例如，@luca/flag 包的元数据将在以下 URL 提供服务

https://jsr.deno.org.cn/@luca/flag/meta.json

此元数据包含包的已发布版本列表。这允许工具发现包的可用版本并执行语义版本控制解析，以确定要使用的最佳版本。

元数据中的每个版本都包含有关版本的信息，例如被撤回状态和包版本的 exports 字段。exports 字段被规范化为简单的对象形式。

对于上面的 @luca/flag 包，元数据将如下所示

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

包版本元数据

包版本元数据是指有关特定包版本的信息。

版本元数据以 JSON 格式提供，地址如下：

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

例如，@luca/flag 包版本 1.0.0 的元数据将通过以下 URL 提供：

https://jsr.deno.org.cn/@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 中创建的，并且仅在短时间内有效。它们只能用于发布包。

设备访问令牌和个人访问令牌都通过带有 Bearer 前缀的 Authorization 标头传递。GitHub Actions OIDC 令牌通过带有 githuboidc 前缀的 Authorization 标头传递。

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

权限

管理 API 具有可以授予令牌的各种权限。这些权限是

  • package/publish：仅允许发布特定包，可能在特定版本。
  • 全部：允许所有操作，但令牌管理除外。

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 是否适合您的用例，请通过 [email protected] 与我们联系。

在 GitHub 上编辑此页面