Skip to content

API.md

Latest commit

 

History

History
241 lines (192 loc) · 6.29 KB

API.md

File metadata and controls

241 lines (192 loc) · 6.29 KB
Raw

API 文档

本文档描述 OWER-API v3 对外提供的所有 HTTP 接口。交互式文档可在服务启动后访问 /docs。

通用约定

  • 基础地址：/v3/api

  • 请求方式：全部为 GET

  • 鉴权：所有 /v3/api/* 接口需在请求头携带密钥：

    authorization: <AUTH_SECRET>

  • 链路追踪：每个响应头包含 X-Request-ID；客户端也可通过请求头 X-Request-ID 主动指定。响应体中亦包含 requestId。

  • BattleTag 格式：名称#数字，名称 2–20 字符（支持中文、字母、数字），# 后为 3–6 位数字。

响应结构

成功：

{
  "success": true,
  "data": { },
  "requestId": "l757TrsB9ol2I5m9Rb87T",
  "timestamp": 1783702722638
}

失败：

{
  "success": false,
  "error": {
    "code": "INVALID_BATTLETAG",
    "message": "战网账号格式无效",
    "requestId": "l757TrsB9ol2I5m9Rb87T"
  },
  "timestamp": 1783702722638
}

注意：大部分业务失败（参数错误、玩家未找到、外部抓取失败等）仍以 HTTP 200 返回，通过 success 字段区分成功与失败；仅鉴权失败（401）、限流（429）、服务器内部错误（500）使用对应的 HTTP 状态码。

GET /v3/api/career

获取玩家生涯信息，包含基础信息、竞技段位、常用英雄与游戏数据统计。

参数

参数 位置 类型 必填 默认 说明
battle_tag query string 是 — 战网账号，格式 名称#数字

请求示例

curl "http://127.0.0.1:16525/v3/api/career?battle_tag=Player%231234" \
  -H "authorization: <AUTH_SECRET>"

响应示例

{
  "success": true,
  "data": {
    "baseInfo": {
      "battleTag": "Player#1234",
      "playerName": "Player",
      "playerNumTag": "1234",
      "title": "团队破坏者",
      "avatarUrl": "https://.../portrait.png",
      "endorsement": 3,
      "namecardID": null,
      "avatarID": null
    },
    "competitive": {
      "PC": { "tank": { "level": "Platinum", "tier": 3 }, "damage": null, "support": null },
      "Console": { "tank": null, "damage": null, "support": null }
    },
    "commonHeroes": [
      { "heroID": 1, "heroName": "Ana", "role": "support", "gamesPlayed": 120, "winPercentage": 53.2, "kda": "3.15" }
    ],
    "gameStats": {
      "PC": { "quickPlay": {}, "competitive": {} },
      "Console": {}
    }
  },
  "requestId": "l757TrsB9ol2I5m9Rb87T",
  "timestamp": 1783702722638
}

GET /v3/api/games

获取指定平台、模式、数据类型的游戏数据排行。

参数

参数 位置 类型 必填 默认 说明
battle_tag query string 是 — 战网账号
platform query string 否 pc pc 或 console
gamemode query string 否 quickplay quickplay 或 competitive
type query string 否 time-played 数据类型，取值见下表

type 可选值（来自 src/data/typeToCategoryIdMap.json）：

time-played、games-won、win-percentage、best-weapon-accuracy、eliminations-per-life、best-kill-streak、best-multikill、avg-eliminations、avg-deaths、avg-final-blows、avg-solo-kills、avg-objective-kills、avg-objective-time、avg-hero-damage、avg-healing-done

请求示例

curl "http://127.0.0.1:16525/v3/api/games?battle_tag=Player%231234&platform=pc&gamemode=quickplay&type=time-played" \
  -H "authorization: <AUTH_SECRET>"

响应示例

{
  "success": true,
  "data": {
    "baseInfo": { "battleTag": "Player#1234", "playerName": "Player" },
    "gamesInfo": {
      "platform": "pc",
      "gamemode": "quickplay",
      "type": "time-played",
      "data": [
        { "heroName": "Ana", "heroData": "12 hours" }
      ]
    }
  },
  "requestId": "l757TrsB9ol2I5m9Rb87T",
  "timestamp": 1783702722638
}

GET /v3/api/heroes

获取指定英雄的详细数据分类统计。

参数

参数 位置 类型 必填 默认 说明
battle_tag query string 是 — 战网账号
platform query string 否 pc pc 或 console
gamemode query string 否 quickplay quickplay 或 competitive
hero_id query integer 否 0 英雄 ID（见 src/data/heroes.json，0 表示全英雄）

请求示例

curl "http://127.0.0.1:16525/v3/api/heroes?battle_tag=Player%231234&hero_id=1" \
  -H "authorization: <AUTH_SECRET>"

响应示例

{
  "success": true,
  "data": {
    "baseInfo": { "battleTag": "Player#1234", "playerName": "Player" },
    "heroesInfo": {
      "platform": "pc",
      "gamemode": "quickplay",
      "heroID": 1,
      "heroName": "Ana",
      "data": [
        {
          "categoryName": "Combat",
          "categoryData": [
            { "statName": "Eliminations", "statValue": "1,234" }
          ]
        }
      ]
    }
  },
  "requestId": "l757TrsB9ol2I5m9Rb87T",
  "timestamp": 1783702722638
}

错误码

统一错误码枚举（src/shared/errors/ErrorCode.ts）：

错误码 典型 HTTP 状态 含义
INVALID_PARAMETER 200 请求参数错误（如 platform / gamemode / type / hero_id 非法）
INVALID_BATTLETAG 200 战网账号格式无效
PLAYER_NOT_FOUND 200 玩家不存在、生涯未公开，或该英雄无数据
UNAUTHORIZED 401 鉴权失败（authorization 头缺失或错误）
RATE_LIMITED 429 请求过于频繁（details.retryAfter 提示可重试秒数）
BLIZZARD_API_ERROR 200 抓取或处理官方页面时出错
REDIS_ERROR — 缓存相关错误（保留）
INTERNAL_ERROR 500 未预期的服务器内部错误

错误响应示例

限流：

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "请求过于频繁，请稍后重试",
    "details": { "retryAfter": 42 },
    "requestId": "l757TrsB9ol2I5m9Rb87T"
  },
  "timestamp": 1783702722638
}

鉴权失败：

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "鉴权失败",
    "requestId": "l757TrsB9ol2I5m9Rb87T"
  },
  "timestamp": 1783702722638
}