mtgonline/ENDPOINT_AUDIT.md

Backend Endpoint Audit Report

Date: 2026-07-24
Scope: Roadmap Section 2.2 - API Endpoints
Status: ✅ Review Complete

---

Executive Summary

The backend has implemented a simplified card import feature that differs significantly from the roadmap specification. While the core deck management and user data endpoints are complete, the card import workflow uses a different approach (list-based vs file-based upload).

---

Section 2.2 - User Deck CRUD ✅ COMPLETE

All deck management endpoints are implemented and match the roadmap:

Roadmap Endpoint	Status	Implementation
POST /decks/	✅	Create user deck with DRAFT status
GET /decks/	✅	List decks with filtering (status, folder, precedent) and pagination
GET /decks/{deck_id}	✅	Get full deck details with cards
PATCH /decks/{deck_id}	✅	Update deck (name, status, folder)
POST /decks/{deck_id}/finalize	✅	Transition DRAFT → FINAL
DELETE /decks/{deck_id}	✅	Delete deck (admin override for FINAL)
GET /decks/{deck_id}/cards	✅	List cards with quantities and details

Location: backend/app/routers/decks.py
Router Prefix: /decks (included in main.py)

---

Section 2.2 - Card Search & Suggestions ⚠️ PARTIAL

Implemented Endpoints

Endpoint	Status	Notes
GET /api/mtg/cards/search	✅	Search cards by name (no type/set/color filters)
GET /api/mtg/cards/{card_name}	✅	Get card by name
GET /api/mtg/cards/sets	✅	List all sets
GET /api/mtg/cards/sets/{set_code}	✅	Get specific set
GET /api/mtg/cards/set/{set_code}	✅	Get cards in set

Location: backend/app/routers/card_router.py
Router Prefix: /api/mtg/cards (NOTE: /mtg/cards not /api/cards)

Missing Endpoints

Roadmap Endpoint	Status	Issue
GET /api/cards/search?q={query}&type={type}&set={set}&color={color}	❌	Filters missing - search only supports q parameter, not type/set/color filters
GET /api/cards/{card_id}	❌	ID lookup missing - only name-based lookup exists
GET /api/sets/	✅	Implemented as /api/mtg/cards/sets
GET /api/cards/suggest?deck_id={deck_id}&limit={n}	❌	Suggestion endpoint missing - no card suggestion functionality

Additional Card Endpoints (Not in Roadmap)

Endpoint	Status	Notes
GET /api/mtg/cards/types	✅	Get unique card types
GET /api/mtg/cards/rarities	✅	Get unique card rarities
GET /api/mtg/cards/statistics	✅	Database statistics

---

Section 2.2 - Card Import ❌ SIGNIFICANT DIFFERENCES

Roadmap Specification

The roadmap specified a file-based import workflow:

• POST /cards/import — Upload file (XLSX, CSV, JSON, ODS)
• GET /cards/import/{import_id}/status — Check import progress
• GET /cards/import/{import_id}/results — Get match results with confidence
• POST /cards/import/{import_id}/confirm — Confirm import
• GET /user/cards — List user's imported cards
• DELETE /user/cards/{card_import_id} — Remove from user cards

Current Implementation

The actual implementation uses a simplified list-based approach:

Current Endpoint	Roadmap Equivalent	Status
POST /api/v1/card-import/	POST /cards/import	✅ Functionally different - accepts card name list, not file upload
GET /api/v1/card-import/status	GET /cards/import/{import_id}/status	⚠️ Simplified - returns current import status, not batch progress
GET /api/v1/card-import/summary	GET /cards/import/{import_id}/results	⚠️ Simplified - returns match summary, not detailed results
Missing	POST /cards/import/{import_id}/confirm	❌ Not implemented - no confirmation step
GET /api/v1/user-data/collection	GET /user/cards	✅ Implemented under user data
DELETE /api/v1/user-data/collection/{card_id}	DELETE /user/cards/{card_import_id}	⚠️ Different - deletes by card_id, not import_id

Implementation Details

Current Card Import Flow:

1. User sends POST /api/v1/card-import/ with card name list
2. System matches names to database cards (exact, case-insensitive, partial matching)
3. Results stored in user_card_imports table as JSON
4. User can view status and summary via GET endpoints

Missing File Upload:

• No file parsing (XLSX, CSV, JSON, ODS)
• No batch processing
• No import ID tracking
• No confirmation workflow

---

Section 2.2 - User Data Endpoints ✅ COMPLETE

All user data endpoints are implemented:

Replays

Endpoint	Status
POST /api/v1/user-data/replays/	✅
GET /api/v1/user-data/replays/{replay_id}	✅
PATCH /api/v1/user-data/replays/{replay_id}	✅
DELETE /api/v1/user-data/replays/{replay_id}	✅

Collection (Cards)

Endpoint	Status
POST /api/v1/user-data/collection/	✅
GET /api/v1/user-data/collection/	✅
PATCH /api/v1/user-data/collection/{card_id}	✅
DELETE /api/v1/user-data/collection/{card_id}	✅

Groups

Endpoint	Status
POST /api/v1/user-data/groups/	✅
GET /api/v1/user-data/groups/	✅
GET /api/v1/user-data/groups/{group_id}	✅
PATCH /api/v1/user-data/groups/{group_id}	✅
DELETE /api/v1/user-data/groups/{group_id}	✅

Networks

Endpoint	Status
POST /api/v1/user-data/networks/	✅
GET /api/v1/user-data/networks/	✅
GET /api/v1/user-data/networks/{network_id}	✅
PATCH /api/v1/user-data/networks/{network_id}	✅
DELETE /api/v1/user-data/networks/{network_id}	✅

Preferences

Endpoint	Status
GET /api/v1/user-data/preferences/	✅
PATCH /api/v1/user-data/preferences/	✅

Activity

Endpoint	Status
GET /api/v1/user-data/activity/	✅

Location: backend/app/routers/user_data.py
Router Prefix: /api/v1/user-data

---

Section 2.2 - Deck Precedents ✅ COMPLETE

Endpoint	Status
GET /decks/precedents	✅
POST /decks/precedents	✅
GET /decks/precedents/{precedent_id}	✅
POST /decks/precedents/{precedent_id}/use	✅

Location: backend/app/routers/decks.py

---

Section 2.2 - Card Suggestions ✅ PARTIAL

Endpoint	Status
GET /decks/{deck_id}/suggestions	✅
POST /decks/{deck_id}/suggestions	✅

Note: These are deck-specific suggestions (add to deck), not the general card suggestion endpoint from the roadmap (GET /api/cards/suggest).

---

Summary of Gaps

Critical Missing Features

1. File-based card import workflow

   • No file upload (XLSX, CSV, JSON, ODS parsing)
   • No batch processing with import IDs
   • No confirmation step
   • No progress tracking

2. Card search filters

   • Search endpoint missing type, set, and color filters
   • Only supports name search

3. Card ID lookup

   • No endpoint to get card by ID
   • Only name-based lookup exists

4. General card suggestions

   • No GET /api/cards/suggest endpoint
   • Only deck-specific suggestions exist

Implemented but Different from Roadmap

1. Card import approach - List-based vs file-based
2. Router prefix - /api/mtg/cards vs /api/cards
3. Deck suggestions - Deck-specific vs general card suggestions

---

Recommendations

Option A: Align with Roadmap (Recommended)

Implement the file-based import workflow:

1. Add file upload endpoint with XLSX/CSV/JSON/ODS parsing
2. Create import batch processing with progress tracking
3. Add confirmation step for matching results
4. Implement card search filters (type, set, color)
5. Add card ID lookup endpoint
6. Implement general card suggestion service

Option B: Simplify Roadmap

Accept the current simplified implementation:

1. Document the simplified card import approach
2. Update ROADMAP.md to reflect actual implementation
3. Consider adding file upload as future enhancement

---

File Locations

Feature	File
Deck CRUD	backend/app/routers/decks.py
Card Search	backend/app/routers/card_router.py
Card Import	backend/app/routers/card_import.py
User Data	backend/app/routers/user_data.py
Deck Precedents	backend/app/routers/decks.py
Deck Suggestions	backend/app/routers/decks.py

---

Next Steps

1. Decide on card import approach (file-based vs list-based)
2. If file-based: Implement file upload and parsing services
3. If list-based: Update ROADMAP.md to reflect actual implementation
4. Add missing search filters to card search endpoint
5. Add card ID lookup endpoint
6. Implement general card suggestion service

---

Audit Complete: 2026-07-24T04:20:00Z