Catalog 数据

先使用直接路由

普通应用使用读取当前数据的短 URL：

GET /api/v1/{resource}
GET /api/v1/{resource}/{id}
GET /api/v1/{resource}?server=jp
GET /api/v1/{resource}/{id}?server=jp

默认 server 是 intl。server query 用于选择活动 server。这些路径与 /api/v1/servers/{server}/{resource} 使用同一个 catalog handler；显式形式用于同时需要 release 参数的 build 和 archive 工具。

常见 resource name 包括 songs、bands、characters、cards、stories、events、audio、videos 和 voices。选定 catalog 才是权威来源，请使用它提供的 resource name、ID、view 和 relation，不要维护硬编码列表。

索引和实体

试一试：选择歌曲和服务器。把 ID 换成索引里的任意 musicId。

GET /api/v1/songs/{id}

id server

尚未发送

Index 请求返回 provider-shaped document。Collection resource 通常返回以 entity ID 为键的 object：

curl --fail-with-body https://haneoka.org/api/v1/songs

{
  "100001": {
    "musicId": 100001,
    "musicTitle": ["迷星叫", "Mayoiuta", "迷星叫", "迷星叫", "헤매는 노래"],
    "bandId": 1,
    "difficulty": [
      { "difficulty": 0, "difficultyName": "easy", "displayLevel": 9, "noteCount": 342 }
    ],
    "jacketUrl": "/assets/intl/Assets/AddressableResources/Image/Jacket/jkt_001_100001.png",
    "musicUrl": "/runtime/intl/cri/sound/musicscore/M_Mayoiuta/1_M_Mayoiuta.mp3"
  }
}

使用 key 读取完整 entity：

curl --fail-with-body https://haneoka.org/api/v1/songs/100001

Entity 可能比 index 项目包含更多字段，例如本地化创作者、发布日期、combo rewards、谱面路径和 video IDs。保留未知字段，并把 null 视为 source 当前没有值。其他 resource 有自己的 shape；events document 使用 entries 和 hasGameEvents，而不是歌曲字段。

可选分页

Collection 和已声明的 view 可通过 limit 获取分页 envelope。这项接口属于准备发布的 Worker 更新，采用时应同时部署对应客户端。

GET /api/v1/songs?server=intl&limit=20
GET /api/v1/{resource}/views/{view}?server=intl&limit=20

{
  "items": [{ "id": "100070", "value": { "musicId": 100070 } }],
  "total": 84,
  "limit": 20,
  "nextCursor": "opaque-cursor-from-the-response",
  "release": {
    "schema": "haneoka-resource-release-identity-v1",
    "server": "intl",
    "releaseId": "r-0123456789abcdef0123",
    "sourceId": "source-snapshot-id"
  }
}

示例缩略了实体字段，实际条目与 count 来自所选 catalog。limit 为 1–100，仅传 cursor 时默认 50。每次最多扫描 8 个实体分片，因此页长可能小于 limit，空页也可能仍有 nextCursor。只在 nextCursor === null 时结束。顺序按分片和分片内 ID 字典序，不是游戏顺序或数字 ID 顺序。

用 URLSearchParams 原样传回 cursor。它固定第一页 release，并绑定 server/resource/view；当前指针推进后仍继续原快照。错误或不匹配的 cursor 返回 400 invalid_cursor，快照不可用返回 404 release_not_found；后者应重新读取第一页。只有有实体存储的 collection/view 支持分页。省略 limit/cursor 保留完整 index；id 批量不能与分页混用。

const scope = { server: "intl", limit: "20" };
let cursor;
do {
  const query = new URLSearchParams(scope);
  if (cursor) query.set("cursor", cursor);
  const response = await fetch(`https://haneoka.org/api/v1/songs?${query}`);
  if (!response.ok) throw new Error(`Catalog HTTP ${response.status}`);
  const page = await response.json();
  for (const { id, value } of page.items) console.log(id, value);
  cursor = page.nextCursor;
} while (cursor !== null);

类型化客户端提供 envelope 校验与实体 decode。

批量读取

GET /api/v1/songs?id=100001&id=100002

尚未发送

重复 id 读取一组 entity：

curl --fail-with-body \
  'https://haneoka.org/api/v1/songs?id=100001&id=100002&server=jp'

响应为：

{
  "items": {
    "100001": { "musicId": 100001, "musicTitle": ["迷星叫", "Mayoiuta"] }
  },
  "missing": ["100002"]
}

items 使用请求的 ID 作为 key；没有 entity 的 ID 出现在 missing。提交 1–100 个 id 参数，去重前计算参数数量。API 会排序并去重 ID，以稳定缓存。

视图和关系

GET /api/v1/servers/{server}/catalog

server

尚未发送

Catalog manifest 会为 resource 声明可选 view 和 relation。View 是有自己 index 和 entity shape 的命名 projection：

GET /api/v1/{resource}/views/{view}
GET /api/v1/{resource}/views/{view}/{id}
GET /api/v1/{resource}/views/{view}?id={id}&id={id}

Relation 使用 resource、relation name 和 key：

GET /api/v1/{resource}/relations/{relation}/{key}

Manifest 中的 valueMode 说明结果。ids relation 会展开为以 ID 为键的 canonical entity；records relation 直接返回 provider record。已声明但没有值的 relation key 返回 {}。

需要这些名称时读取所选 server 的 manifest：

curl --fail-with-body https://haneoka.org/api/v1/servers/intl/catalog

Manifest 描述 resource kind、count、index path、entity store、view path 与 shape、relation name 和 dependencies。Storage 字段适合 crawler；普通应用可以继续使用直接路由。

对调用方有用的字段语义

字段模式	使用方式
`musicTitle`、`bandName` 等本地化数组	选择文档规定的 locale 位置，值为空时提供 fallback；保留数组以支持之后切换 locale。
`*Url` 和 `file` path	以 `https://haneoka.org` 为基准解析，需要二进制时发送到对应 media 或 game-client 路由。
Difficulty record	分别读取 `difficultyName`、`displayLevel`、`playLevel`、`sortLevel` 和 `noteCount`，保留 chart `file` path。
`musicId`、`bandId`、`videoIds` 等 ID	保留 source 的数字或字符串类型；ID 规则由 resource 定义。
`null`	Source 当前没有值，不要转换为空字符串。

高级显式形式

Server-scoped 请求使用：

GET /api/v1/servers/{server}/{resource}
GET /api/v1/servers/{server}/{resource}/{id}

只有可重现 build 或 archive 需要固定 catalog 时，才添加 release=r-<20 lowercase hex characters>。高级服务器接口介绍 release、source、media 和 storage surface。