# Blizzard API coverage

Where the suite currently stands against Blizzard's Battle.net API families. Status is derived from the actual codebase — endpoints wired and called in production code paths, not planned or aspirational.

**Legend:**

- **Implemented** — endpoint is called from a Sync or CharacterDataProvider and its data lands in Drupal storage.
- **Partial** — endpoint is wrapped in an Api class but not all of its data is persisted, or only specific sub-resources are covered.
- **Planned** — explicitly planned; extension point exists but no implementation.
- **Not started** — no current coverage.
- **Won't implement** — deliberately not synced; hardcoded or out of scope by design.

Blizzard splits their Battle.net WoW API into two families: **Game Data** (global, app-token) and **Profile** (per-player, user-OAuth-token). Coverage is tracked separately.

**Note on auth in this codebase:** Blizzard accepts an app-scoped token on most Profile endpoints too — the per-user OAuth requirement only applies to endpoints that touch the logged-in user's own data (`/profile/user/wow`, Protected Character Profile, etc.). Today this suite calls every per-character and per-guild Profile endpoint with the app token via `BattleNetClient::get()` unless a user token is passed explicitly. Only `AccountProfileApi` in `wow_user` passes a stored user token — it needs one because `/profile/user/wow` is user-scoped.

---

## Game Data APIs

| API family | Representative endpoints | Module | Status | Notes |
|---|---|---|---|---|
| Achievement | `/data/wow/achievement-category/index` + `/{id}`<br>`/data/wow/achievement/index` + `/{id}`<br>`/data/wow/media/achievement/{id}` | `wow_achievement` | Implemented | Categories synced into two taxonomies (character + guild). Achievements synced as content entities via queue. Media resolved on demand. |
| Azerite Essence | — | — | Not started | |
| Connected Realm | `/data/wow/connected-realm/index` + `/{id}` | `wow_realm` | Partial | Called for realm metadata lookup; connected-realm groupings are used but no dedicated storage for connection group entities. |
| Covenant | — | — | Not started | |
| Creature | `/data/wow/creature/{id}`<br>`/data/wow/creature-type/index`<br>`/data/wow/creature-family/index`<br>`/data/wow/media/creature-display/{id}`<br>`/data/wow/search/creature` | `wow_creature` | Implemented | Creature types and families synced as taxonomies. Individual creatures looked up on demand. Creature display media resolved per creature. Search API used for remote search fallback. |
| Guild Crest | `/data/wow/media/guild-crest/{type}/{id}` | `wow_guild` | Partial | Called to fetch crest media for a specific guild. The crest catalog endpoints (`guild-crest/components/index`) are not synced. |
| Heirloom | — | — | Not started | |
| Item | `/data/wow/item-class/index` + `/{id}`<br>`/data/wow/item/{id}`<br>`/data/wow/media/item/{id}`<br>`/data/wow/search/item` | `wow_item` | Partial | Item classes synced as a taxonomy. Items fetched on demand when referenced (by achievement criteria, gear slots, etc.) — no bulk item catalog. Canonical page at `/wow/item/{id}/{slug}`. Blizzard Search API used for remote search fallback. |
| Journal | — | — | Not started | |
| Media (generic) | `/data/wow/media/*` | core | Partial | Supported via `WoWMediaTrait`; each submodule pulls its own entity-type media. |
| Modified Crafting | — | — | Not started | |
| Mount | `/data/wow/mount/index` + `/{id}`<br>`/data/wow/media/mount/{id}` | `wow_mount` | Implemented | |
| Mythic Keystone | — | — | Not started | |
| Mythic Raid Leaderboard | — | — | Not started | |
| Pet | `/data/wow/pet/index` + `/{id}`<br>`/data/wow/media/pet/{id}` | `wow_pet` | Implemented | |
| Playable Class | `/data/wow/playable-class/index` + `/{id}`<br>`/data/wow/media/playable-class/{id}` | `wow_playable_class` | Implemented | |
| Playable Race | `/data/wow/playable-race/index` + `/{id}` | `wow_playable_race` | Implemented | |
| Playable Specialization | `/data/wow/playable-specialization/index` + `/{id}`<br>`/data/wow/media/playable-specialization/{id}` | `wow_playable_specialization` | Implemented | |
| Power Type | `/data/wow/power-type/index` + `/{id}` | `wow_power_type` | Implemented | |
| Profession | — | — | Not started | |
| PvP Season / Tier / Region | — | — | Not started | |
| Quest | `/data/wow/quest/index`<br>`/data/wow/quest/{id}`<br>`/data/wow/quest-type/index` | `wow_quest` | Implemented | Quest types synced as taxonomy. Quests synced as content entities via batch queue. Canonical page at `/wow/quest/{id}/{slug}`. |
| Realm | `/data/wow/realm/index` + `/{id}` | `wow_realm` | Implemented | |
| Region | `/data/wow/region/index` + `/{id}` | — | Won't implement | The five regions (US, EU, KR, TW, CN) are Blizzard infrastructure, not game content — they never change. `Drupal\wow\Enum\Region` hardcodes them as a PHP enum with per-region API hosts, OAuth hosts, locale maps, and the CN credential separation. Syncing dynamically would add complexity for no practical benefit. |
| Reputation Faction / Tier | `/data/wow/reputation-faction/index` + `/{id}` | `wow_reputation` | Partial | Faction catalog synced. Reputation tier endpoint is not synced; tier names come from the per-character reputations data. |
| Spell | — | — | Not started | |
| Talent | — | — | Not started | |
| Tech Talent | — | — | Not started | |
| Title | `/data/wow/title/index` + `/{id}` | `wow_title` | Implemented | |
| Toy | `/data/wow/toy/index` + `/{id}`<br>`/data/wow/media/toy/{id}` | `wow_toy` | Implemented | |
| WoW Token | — | — | Not started | |
| Guild (as Game Data) | `/data/wow/guild/{realm}/{name}`<br>+ `/roster`, `/achievements`, `/activity` | `wow_guild` | Partial | `GuildApi` wraps all four endpoints. Only the profile endpoint and the crest media are persisted (`wow_guild` entity). Roster, guild achievements, and guild activity are exposed to `GuildDataProvider` plugins — the manager, interface, and tests exist, but no in-tree plugins consume them yet. |

---

## Profile APIs

All per-character Profile endpoints run from the `wow_character.sync.character` service via its registered `CharacterDataProvider` plugins. Today those calls use the **app token** — Blizzard accepts that on per-character endpoints, so no user OAuth is required to fetch data for a character you know by realm + name. A user OAuth token is only used where Blizzard specifically requires it (account-profile endpoints below, and Protected Character Profile — not currently implemented).

| API family | Representative endpoints | Module | Status | Notes |
|---|---|---|---|---|
| Account Profile | `/profile/user/wow` | `wow_user` | Implemented | Used to list a logged-in player's characters during the selection flow. |
| Character Profile | `/profile/wow/character/{realm}/{name}` | `wow_character` | Implemented | Core character summary — level, class, race, faction, spec, ilvl, guild name, etc. |
| Character Media | `/profile/wow/character/{realm}/{name}/character-media` | `wow_character` | Implemented | Avatar + inset render cached to `public://wow/character/`. |
| Character Achievements | `/profile/wow/character/{realm}/{name}/achievements` | `wow_achievement` | Implemented | Stored in `wow_achievement_progress` junction. |
| Character Achievements Statistics | — | — | Not started | |
| Character Appearance | — | — | Not started | |
| Character Collections (Mounts) | `/profile/wow/character/{realm}/{name}/collections/mounts` | `wow_mount` | Implemented | `wow_mount_collection` junction. |
| Character Collections (Pets) | `/profile/wow/character/{realm}/{name}/collections/pets` | `wow_pet` | Implemented | `wow_collected_pet` junction — includes nickname, level, breed. |
| Character Collections (Toys) | `/profile/wow/character/{realm}/{name}/collections/toys` | `wow_toy` | Implemented | `wow_toy_collection` junction. |
| Character Collections (Heirlooms) | — | — | Not started | |
| Character Collections (Transmogs) | — | — | Not started | |
| Character Encounters | — | — | Not started | Dungeons + raids, PvP encounters. |
| Character Equipment | — | — | Not started | Would require `wow_item` item sync coverage to be meaningful. |
| Character Hunter Pets | — | — | Not started | |
| Character Mythic Keystone Profile | — | — | Not started | |
| Character Professions | — | — | Not started | |
| Character PvP | — | — | Not started | PvP bracket summaries. |
| Character Quests | — | — | Not started | |
| Character Reputations | `/profile/wow/character/{realm}/{name}/reputations` | `wow_reputation` | Implemented | `wow_reputation_standing` junction stores the base standing (tier, raw/max points, standing name). Paragon and Renown data is returned on the same endpoint but not persisted — `wow_reputation_standing` has no field for them. |
| Character Soulbinds | — | — | Not started | Expansion-specific. |
| Character Specializations | — | — | Not started | Active spec comes from the base Character Profile endpoint; spec history and talents are not synced. |
| Character Statistics | — | — | Not started | |
| Character Titles | `/profile/wow/character/{realm}/{name}/titles` | `wow_title` | Implemented | `wow_title_award` junction. |
| Guild (profile-scope) | — | — | Not started | Guild data currently comes entirely from the Game Data guild endpoints; per-user guild context is not separately synced. |
| Protected Character Profile | — | — | Not started | Requires an elevated OAuth scope. |

---

## What's implemented across BOTH families

Per-character collection + achievement tracking is the best-covered area: it uses a Game Data catalog sync (the "what exists" dictionary) + a Profile API per-character sync (the "what this player has" overlay). This pair is fully implemented for achievements, mounts, pets, titles, toys, and reputations.

## Biggest gaps

- **Equipment / gear details** — no item catalog sync, no `/equipment` endpoint. A full gear page would need both.
- **Mythic+ and PvP** — completely untouched. These are the main competitive-content endpoints.
- **Professions / recipes** — also untouched. Would be a substantial addition.
- **Appearance / transmog** — not started.

If you're planning to use the suite for a cosmetic-collection site (mounts, pets, titles, toys, reputations, achievements), coverage is strong. For a progression-tracking site (PvP rating, raid logs, Mythic+ score), expect to build additional integration.
