CN Tierlist API 文档

CN Tierlist API 为开发者和玩家提供对CN Tierlist数据的程序化访问接口，支持玩家信息管理、Tier排行记录等功能。 基于 ASP.NET Core + Razor Pages 构建，所有数据请求均需使用 API Key 验证身份。 本页由 AI 生成。

API Key 认证

所有请求需在 Header 中添加 X-Api-Key 参数，未授权请求将被拒绝。如果你需要一个 API Key，请邮件至 huangyu@huangyu.win

权限控制

写操作需要具有写权限的 API Key，否则将返回一个错误页面(HTML)。

数据安全

所有数据均使用服务器端验证，避免非法操作和数据污染。

重要注意事项

  • 所有 POST/PUT/DELETE 操作需要 write 权限的 APIKEY
  • API 返回数据均为 JSON 格式
  • 所有日期时间均使用 UTC 时间格式
  • API 更新时间为北京时间 2025年7月25日

玩家管理 API

GET /api/v1/players 需要API Key

获取所有玩家及其Tier记录信息

请求参数

参数位置 参数名 类型 说明
Header X-Api-Key string 用于认证的有效API Key

响应示例

[
  {
    "id": 1,
    "uuid": "d8d3a9e0-5f1e-4b0d-8245-0b5b8f7d8c5f",
    "region": "华东",
    "isBlacklisted": false,
    "blacklistDate": null,
    "blacklistReason": null,
    "tierRecords": [
      {
        "id": 101,
        "mode": "Axe",
        "isRetired": false,
        "currentTier": "LT5",
        "peakTier": "HT5",
        "lastUpdated": "2025-07-24T12:34:56.789Z"
      }
    ]
  }
]
GET /api/v1/player/{UUID} 需要API Key

通过UUID获取特定玩家的完整信息

请求参数

参数位置 参数名 类型 说明
Path uuid GUID 玩家的唯一标识符 (如 d8d3a9e0-5f1e-4b0d-8245-0b5b8f7d8c5f)

响应示例

{
  "id": 1,
  "uuid": "d8d3a9e0-5f1e-4b0d-8245-0b5b8f7d8c5f",
  "region": "华南",
  "isBlacklisted": false,
  "blacklistDate": null,
  "blacklistReason": null,
  "tierRecords": [
    {
      "id": 101,
      "mode": "Sword",
      "isRetired": true,
      "currentTier": "HT1",
      "peakTier": "HT1",
      "lastUpdated": "2025-07-24T12:34:56.789Z"
    }
  ]
}
POST /api/v1/player/add 需要写权限

添加新玩家到系统

请求体 (application/json)

{
  "uuid": "d8d3a9e0-5f1e-4b0d-8245-0b5b8f7d8c5f",
  "region": "华南"
}

响应状态

  • 200 OK - 添加成功，返回创建后的玩家信息
  • 400 Bad Request - 玩家已存在
  • 200 OK (HTML) - API Key没有写权限
POST /api/v1/player/update 需要写权限

更新玩家的部分信息（如黑名单状态、地区等）

请求体 (application/json)

{
  "uuid": "d8d3a9e0-5f1e-4b0d-8245-0b5b8f7d8c5f",
  "isBlacklisted": true,
  "blacklistReason": "使用外挂",
  "region": "华南"
}

响应状态

  • 200 OK - 更新成功，返回更新后的玩家信息
  • 404 Not Found - 玩家不存在
  • 200 OK(HTML) - API Key没有写权限
POST /api/v1/player/delete 需要写权限

从系统中删除玩家及其所有Tier记录

请求体 (application/json)

{
  "uuid": "d8d3a9e0-5f1e-4b0d-8245-0b5b8f7d8c5f"
}

响应状态

  • 200 OK - 删除成功
  • 404 Not Found - 玩家不存在

Tier记录管理 API

GET /api/v1/tier/{UUID} 需要API Key

获取指定玩家的所有Tier记录

请求参数

参数位置 参数名 类型 说明
Path uuid GUID 玩家的唯一标识符

响应示例

[
  {
    "id": 101,
    "mode": "Vanilla",
    "isRetired": false,
    "currentTier": "LT2",
    "peakTier": "LT1",
    "lastUpdated": "2025-07-24T12:34:56.789Z"
  },
  {
    "id": 102,
    "mode": "BUHC",
    "isRetired": true,
    "currentTier": "HT1",
    "peakTier": "HT1",
    "lastUpdated": "2025-07-20T08:12:34.567Z"
  }
]
POST /api/v1/tier/update 需要写权限

更新玩家的Tier记录（创建新记录或更新现有记录）

请求体 (application/json)

{
  "uuid": "d8d3a9e0-5f1e-4b0d-8245-0b5b8f7d8c5f",
  "mode": "Mace",
  "currentTier": "HT1",
  "peakTier": "LT1",
  "isRetired": false
}

响应状态

  • 200 OK - 更新成功，返回更新后的玩家信息
  • 404 Not Found - 玩家不存在
POST /api/v1/tier/delete 需要写权限

删除指定玩家的特定模式Tier记录

请求体 (application/json)

{
  "playerUuid": "d8d3a9e0-5f1e-4b0d-8245-0b5b8f7d8c5f",
  "mode": "Mace"
}

响应状态

  • 200 OK - 删除成功
  • 400 Bad Request - Tier记录不存在
  • 404 Not Found - 玩家不存在
数据模型定义

以下是API中使用的数据结构和枚举类型的详细说明。

数据结构

Player (玩家)

字段名 类型 描述
id int 玩家唯一ID
uuid GUID 玩家UUID
region Region 玩家所属区域
isBlacklisted bool 是否在黑名单中
blacklistDate DateTime? 黑名单截止日期
blacklistReason string? 黑名单原因
tierRecords List<PlayerTierRecord> Tier记录列表

PlayerTierRecord (Tier记录)

字段名 类型 描述
id int 记录唯一ID
mode GameMode 游戏模式
isRetired bool 是否已退役
currentTier TierLevel 当前段位
peakTier TierLevel 历史最高段位
lastUpdated DateTime 最后更新时间(UTC)

枚举类型

Region (区域)

值 描述
华南
华东
华北
华中
西北
西南
东北
香港
澳门
台湾
其他

GameMode (游戏模式)

+
值 描述
Axe 盾斧
Sword 剑
BUHC 极限生存竞赛
Vanilla 水晶
NPOT 合金药水
Potion 钻石药水
SMP 多人生存
Mace 重锤

TierLevel (段位等级)

值 描述
LT5
HT5
LT4
HT4
LT3
HT3
LT2
HT2
LT1
HT1