Skip to content

BATTLENET_API.md

Latest commit

 

History

History
195 lines (144 loc) · 6.46 KB

BATTLENET_API.md

File metadata and controls

195 lines (144 loc) · 6.46 KB

Battle.net API Reference

Overview

This extension integrates with the Blizzard Battle.net API to provide:

  • Guild roster sync — Automatically import guild members with class, race, level, and rank data
  • Character profiles — Fetch individual character data including talents, titles, and achievements
  • Armory links — Generate links to a character's Blizzard profile page
  • Character portraits — Display character render images from Blizzard's CDN
  • Guild emblems — Generate guild emblem images from API-provided emblem data
  • Realm status — Query realm availability

Authentication

The API uses OAuth 2.0 Client Credentials Grant:

  1. Client sends POST https://oauth.battle.net/token with grant_type=client_credentials and Authorization: Basic base64({client_id}:{client_secret})
  2. Blizzard responds with { "access_token": "...", "expires_in": 86400 }
  3. All subsequent API requests include Authorization: Bearer {access_token} and Battlenet-Namespace: {type}-{region}

Token caching: Tokens are cached using phpBB's cache service with key bbguild_wow_oauth_token_{region}. On 401 response, the cached token is invalidated and the request is retried once.

CN region: Uses https://oauth.battlenet.com.cn/token instead.

API Endpoints

Region Base URL
US https://us.api.blizzard.com/
EU https://eu.api.blizzard.com/
KR https://kr.api.blizzard.com/
TW https://tw.api.blizzard.com/

Namespace Types

Every API request requires a Battlenet-Namespace header:

Type Used For Example
dynamic-{region} Realm status dynamic-eu
profile-{region} Guild and character data profile-us
static-{region} Achievement data static-kr

API Architecture

Class Hierarchy

battlenet_resource (abstract base — OAuth 2.0 + caching)
      ├── battlenet_guild
      ├── battlenet_character
      ├── battlenet_realm
      └── battlenet_achievement

battlenet (factory)
      └── creates guild/character/realm/achievement instances

Request Flow

  1. Caller creates battlenet($type, $region, $apikey, $locale, $privkey, $ext_path, $cache)
  2. Factory instantiates the appropriate resource subclass and sets namespace type
  3. Resource's method (e.g. getGuild()) calls consume($method, $params)
  4. consume() builds the request URL, checks cache, obtains OAuth token, sends Bearer-authenticated request
  5. On 401, token is refreshed and request retried once
  6. Response is JSON-decoded and cached for the configured TTL (default 3600s)

Caching

All API responses are cached using phpBB's cache service:

  • Cache key: bbguild_wow_api_ + base64-encoded full request URL
  • Default TTL: 3600 seconds (1 hour)
  • Cache is stored in phpBB's configured cache backend (file, APCu, Redis, etc.)

OAuth tokens are cached separately:

  • Cache key: bbguild_wow_oauth_token_{region}
  • TTL: token expiry minus 5 minutes (typically ~23.9 hours)

Guild API

Request: GET /{endpoint}/{realm}/{name}?fields={fields}&locale={locale}

Extra fields: members, achievements, news

Response structure (members):

{
  "name": "Guild Name",
  "realm": "Realm Name",
  "battlegroup": "Battlegroup",
  "level": 25,
  "side": 0,
  "achievementPoints": 1234,
  "emblem": {
    "icon": 126,
    "iconColor": "ff101517",
    "border": 0,
    "borderColor": "ff0f1415",
    "backgroundColor": "ffffffff"
  },
  "members": [
    {
      "character": {
        "name": "CharName",
        "realm": "Realm",
        "class": 1,
        "race": 1,
        "gender": 0,
        "level": 110,
        "achievementPoints": 5678,
        "thumbnail": "realm/12/34567890-avatar.jpg"
      },
      "rank": 0
    }
  ]
}

Faction mapping: side: 0 = Alliance (bbGuild faction 1), side: 1 = Horde (bbGuild faction 2)

Character API

Request: GET /{endpoint}/{realm}/{name}?fields={fields}&locale={locale}

Extra fields: achievements, appearance, feed, guild, hunterPets, items, mounts, pets, petSlots, professions, progression, pvp, reputation, stats, talents, titles

Default fields requested by bbGuild: guild, titles, talents

Portrait URL format: https://render.worldofwarcraft.com/character/{region}/{thumbnail}

Armory URL format: https://worldofwarcraft.blizzard.com/en-{region}/character/{region}/{realmSlug}/{name}

Realm API

Request: GET /realm/status?realms={realm1,realm2}&locale={locale}

Achievement API

Request: GET /achievement/{id}?locale={locale}

Error Handling

The API returns structured error responses:

{ "code": 401, "type": "BLZWEBAPI00000401", "detail": "Unauthorized" }
Code Meaning bbGuild Behavior
200 Success Data processed normally
401 Unauthorized Token refreshed and request retried once
403 Forbidden Marks armory as disabled, logs error
404 Not Found Returns KO result
429 Rate Limited Returns error
500+ Server Error Returns KO result, logs error

Configuration

API Credentials

Set in ACP > bbGuild > Games > Edit World of Warcraft:

Field Description
Client ID Your Blizzard API client ID from develop.battle.net
Client Secret Your Blizzard API client secret
Locale Determines the language of API responses (e.g. en_GB, de_DE)

Region

Set per guild in ACP > bbGuild > Guilds > Edit:

Region API Base URL
US https://us.api.blizzard.com/
EU https://eu.api.blizzard.com/
KR https://kr.api.blizzard.com/
TW https://tw.api.blizzard.com/

Minimum Armory Level

Set per guild — only characters at or above this level will be imported during guild sync.

Files

File Purpose
game/wow_api.php Implements game_api_interface, orchestrates API calls
api/battlenet.php Factory — creates resource instances per API type
api/battlenet_resource.php Abstract base — OAuth 2.0 auth, caching, HTTP requests
api/battlenet_guild.php Guild resource — getGuild()
api/battlenet_character.php Character resource — getCharacter()
api/battlenet_realm.php Realm resource — getRealmStatus()
api/battlenet_achievement.php Achievement resource — getAchievementDetail()