接入指南

公共 API v1

查询公开内容与组织,并按授权读取本人资料、维护内容和组织。

公共 API v1 包括公开查询、个人 API、OAuth、机器人事件和精简资源查询。每个接口页都有参数、响应和权限说明;对应的机器可读规范可从接口页下载。本页中的 http://127.0.0.1:4520 是示例地址,实际请求地址以对应接口规范的服务地址为准。机器人账号的申请、令牌与事件消费见机器人账号接入。

精简资源查询

精简资源接口只提供列表、详情和当前兼容构建。完整接口见精简资源参考,机器可读契约见 public-v1.json。

操作接口参考
筛选资源GET /v1/resources
读取详情GET /v1/resources/{slug}
查找当前构建GET /v1/resources/{slug}/updates

三条路径均支持 HEAD,执行与 GET 相同的校验并返回状态和响应头,不发送正文。已知路径的其它方法返回 405 和 Allow: GET, HEAD;未知版本或路径返回 404。

发起查询

curl --get 'http://127.0.0.1:4520/v1/resources' \
  --data-urlencode 'loader=fabric' \
  --data-urlencode 'mc=1.20.1' \
  --data-urlencode 'limit=10'

无需令牌也可读取公开资源。若主动提供 PAT 或 OAuth access token,它必须具备 resource:read:feed;无效、过期、撤销或错误 scope 的凭据返回 401/403,不会退回匿名读取。任何 Cookie 请求头均返回 400;请求不会创建网站会话,也不签发媒体权限。浏览器调用须使用 credentials: 'omit',且只有运营方显式开放 CORS 后才可跨域访问。

const url = new URL('/v1/resources', 'http://127.0.0.1:4520')
url.searchParams.append('loader', 'fabric')
url.searchParams.append('loader', 'quilt')
url.searchParams.set('mc', '1.20.1')
const response = await fetch(url, { credentials: 'omit' })
if (!response.ok) throw new Error(`请求失败:${response.status}`)
const result = await response.json()
console.log(result.items)
// total 是十进制字符串,需要整数运算时用 BigInt(result.total)。

loader、mc、type、tag、capability 支持重复同名参数或逗号分隔,同维度 OR、跨维度 AND。加载器、游戏版本和类型必须由同一原始发布记录同时满足。例如 quilt 和 1.19.4 分别出现在两条记录上时,两者组合不会命中可用构建。加载器族不参与筛选。

q、sort、page、limit、cursor 是单值参数,重复键返回 400。未知参数、非法编码、空多选值及 GET/HEAD 正文也会被拒绝。每维最多 64 个值,每值最多 128 字符;关键字最多 200 个 UTF-16 单元,请求 URI 最多 16 KiB、查询参数最多 256 个。

查询键和值中的 C0(U+0000–U+001F)及 DEL(U+007F)在 trim 去除首尾空白前拒绝,不能用编码后的制表符或换行绕过校验;正常 Unicode 查询与正文文本保留,不使用整段文本过滤。

分页和稳定字段

列表默认为 sort=updated&page=1&limit=20,最多 50 条,页码最多 1000;另可按 downloads 排序。nextCursor 仅用于 updated,继续请求时带上 cursor、保持 page=1 和其它筛选一致。游标不透明,不能解码后自行构造。格式、签名、版本或范围错误返回 400/INVALID_INPUT;列表快照过期时返回 409/CURSOR_STALE,此时从第一页重取。

成功直接返回该接口的对象;错误为 {"error":{"code":"…","message":"…"}}。声明的字段稳定存在,coverUrl、body、nextCursor、更新的 name 和文件 sha512 在无值时为 null,数组为空时为 []。列表 total 和文件 size 均为十进制字符串,避免大整数精度损失。ID、revision 和游标按不透明字符串处理;发布时间保留源字符串中的微秒精度。

详情中的 releaseCount 和 matchedReleaseCount 统计展示合并单元;更新接口返回原始发布记录。详情不包含发布历史,不能从详情的加载器与版本数组任意组合出下载构建。正文是原始文本,应在客户端对应输出上下文转义或安全呈现。

当前更新与条件请求

updates 只接受 loader、mc、type、releaseType 和 limit。渠道默认 release,也可多选 beta/alpha;默认 20、最大 50 条。它是当前公开快照,hasMore 表示还有更旧构建,不提供历史 cursor。

收到 ETag 后可将其原值放入下一次请求的 If-None-Match。条件请求仍会核对令牌有效性和资源可见性;资源撤回或删除不会被旧标签掩盖。304 无正文,200 需要用新快照替换旧结果。安装前应再次复核构建。

公开 ETag 与响应中的绝对地址绑定。地址变化后,旧标签会被视为不匹配并返回 200;应使用新响应中的 ETag,不要用旧标签推断内容未变。未知标签也按不匹配处理;* 保留正常的存在性语义,并仍需通过相同的可见性校验。

响应使用 Cache-Control: private, no-store。429 表示请求超过频率额度,503 表示服务暂不可用;有 Retry-After 时按建议秒数等待。504 表示请求期限已到。单次响应上限为 2 MiB。

文件 url 是绝对地址。请直接使用返回的链接,不要将它重写成公共 API 域名,也不要将 SHA512 当作访问授权。

公开组织与本人资料

组织与本人资料使用同一套 v1 路径。公开组织列表仅包含已批准、公开且未解散的组织;列表可使用 q、page 和 pageSize,每页最多 50 条。详情可返回公开组织资料,或已解散公开组织的最小墓碑。私有组织和成员关系不会进入公开响应。

操作接口所需权限
列出公开组织GET /v1/site/organizations匿名
读取公开组织GET /v1/site/organizations/{slug}匿名
读取本人展示资料GET /v1/personal/meuser:read:self
列出本人组织GET /v1/personal/organizationsorganization:read:self
读取本人组织GET /v1/personal/organizations/{slug}organization:read:self
创建组织POST /v1/personal/organizationsorganization:create
编辑组织资料PUT /v1/personal/organizations/{slug}organization:update:self
curl --get 'http://127.0.0.1:4520/v1/site/organizations' \
  --data-urlencode 'q=创作' \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=20'

/v1/personal 接受具有接口所列 scope 的 PAT 或 OAuth access token,不使用网站 Cookie。user:read:self 只读取本人的展示资料,与 OAuth userinfo 的 profile:read、email:read 分开;个人展示资料只提供读取接口。本人组织列表和详情仅覆盖本人拥有或作为活跃成员加入的组织,已解散组织只返回最小墓碑。浏览器跨域调用还取决于 API 的 CORS 配置,请使用 credentials: 'omit'。

curl 'http://127.0.0.1:4520/v1/personal/me' \
  -H 'Authorization: Bearer <access-token>'

创建组织要求账号可用、邮箱已验证且未被限制发布;创建者成为组织所有者。编辑只允许活跃所有者修改已批准且未解散的组织,必须提交当前正整数 version 和至少一个待修改字段。版本变化时返回 409;请先读取最新资料,再决定是否重试修改。

curl -X PUT 'http://127.0.0.1:4520/v1/personal/organizations/example-team' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  --data '{"version":1,"name":"更新后的组织名称"}'

上述 scope 不授予网站后台或媒体管理权限。文档站不预填或保存令牌,也不代理凭据。