API-First Architecture

Context and Problem Statement

Grand Archive TCG provides an official open API at api.gatcg.com with comprehensive card data, including attributes, editions, sets, circulations, and images. We also have TCGCSV data (category 74) for TCGPlayer product IDs and pricing.

We need to decide the primary data source for the Grand Archive importer. Other games use different strategies:

• SWU: TCGCSV-first (TCGPlayer products drive the import, SWU API enriches)
• Pokemon/MTG: Game API-first (official API drives, TCGCSV provides marketplace IDs)
• FAB: Hybrid (CardVault API primary, TCGCSV for TCGPlayer IDs with deterministic mapping)
• Sheet-based games: Google Sheets primary (Cyberpunk, Rise, Drakerion, etc.)

Decision Drivers

• The GA API is the most comprehensive source of card data (attributes, effects, circulations, flip cards, set metadata)
• The GA API has ~4,800 cards across 54 sets — more granular than TCGPlayer’s 44 groups
• TCGCSV doesn’t provide GA-specific attributes (elements, classes, cost types, etc.)
• Grand Archive has a simple finish model (Standard/Foil only) — no complex variant parsing needed
• Not all GA API sets have TCGPlayer equivalents (Armaments sub-sets, Pantheon Decks, etc.)
• We want every GA card in our system regardless of TCGPlayer availability

Considered Options

1. GA API-first: GA API drives what cards exist, TCGCSV enriches with TCGPlayer IDs
2. TCGCSV-first: TCGPlayer products drive the import, GA API enriches with attributes
3. Sheet-based: Manual data entry via Google Sheets

Decision Outcome

Chosen option: GA API-first, because:

• The GA API provides richer data than TCGCSV (13 elements, 15 card types, 9 classes, cost mechanics, effects, flip card support)
• All 54 sets from the GA API should be importable, even the 5 that don’t exist on TCGPlayer
• The simple Standard/Foil finish model doesn’t require complex TCGCSV suffix parsing
• TCGPlayer ID matching can be layered on top via a deterministic expansion mapping + product-level matching service

Architecture Comparison

Consequences

Positive

• Every GA API card becomes a product, even without a TCGPlayer equivalent
• Full card attributes (elements, classes, costs, effects, flip sides) available from day one
• Card images sourced directly from the GA API (api.gatcg.com/images/cards/)
• Incremental sync possible via the API’s last_update parameter
• No dependency on TCGCSV for core card data

Negative

• Products without TCGPlayer IDs have no pricing data (~9% of catalog in 5 unmapped sets)
• TCGPlayer ID matching requires a separate deterministic mapping table maintained manually
• If the GA API goes down or changes, the entire import fails (no fallback source)
• TCGCSV may have products not in the GA API (unlikely but possible for very new releases)

Impacted Files