mnemo_cards/mnemo_cards_web_v2/API_V2_MIGRATION.md

API v2 Migration Guide

Status: In Progress

The web app is being migrated to use API v2 exclusively. API v2 provides:

• Standard OAuth2/JWT Bearer token authentication
• RESTful endpoint patterns
• Better error handling with standard HTTP status codes
• Token refresh mechanism

Backend Implementation Status

✅ Completed

• Created AuthApiV2 with OAuth2 endpoints
• Created JwtService for token generation/verification
• Created authorizeV2 middleware for Bearer token auth
• Created PacksApiV2 basic structure
• Mounted v2 APIs at /api/v2 path
• Separated v1 and v2 authorization middleware

⚠️ Needs Completion

• Fix JwtService HMAC-SHA256 implementation (use proper crypto library)
• Complete PacksApiV2 endpoints implementation
• Implement TestsApiV2
• Implement GamesApiV2
• Implement PurchasesApiV2
• Implement SubscriptionsApiV2
• Implement PromocodesApiV2
• Add comprehensive error responses
• Add API documentation (OpenAPI/Swagger)

Web App Implementation Status

✅ Completed

• Created ApiConfigV2 with all v2 endpoints
• Created HttpRepositoryV2 with Bearer token auth
• Updated StorageModule to use HttpRepositoryV2
• Updated AuthService to use HttpRepositoryV2
• Updated dependency injection to use v2

⚠️ Needs Completion

• Update GamesManager to use HttpRepositoryV2
• Update TestManager to use HttpRepositoryV2
• Update StatisticsService to use HttpRepositoryV2
• Update SubscriptionService to use HttpRepositoryV2
• Update PromocodeService to use HttpRepositoryV2
• Update PackProgressService to use HttpRepositoryV2
• Write unit tests for HttpRepositoryV2
• Update integration tests

Backend Endpoints

Authentication (/api/v2/auth)

• POST /api/v2/auth/oauth/google - Google OAuth
• POST /api/v2/auth/refresh - Refresh access token
• GET /api/v2/auth/me - Get current user
• POST /api/v2/auth/logout - Logout

Packs (/api/v2/packs)

• GET /api/v2/packs - List packs (with pagination)
• GET /api/v2/packs/{packId} - Get pack details
• GET /api/v2/packs/{packId}/cards - Get pack cards
• GET /api/v2/packs/{packId}/cards/{cardId}/image - Get card image
• GET /api/v2/packs/{packId}/tests - Get pack tests

Tests (/api/v2/tests)

• GET /api/v2/tests/{testId} - Get test
• POST /api/v2/tests/{testId}/results - Submit results
• GET /api/v2/tests/{testId}/history - Get attempt history

Migration Steps

1. Backend: Complete JWT implementation and all v2 endpoints
2. Web App: Update all services to use HttpRepositoryV2
3. Testing: Write comprehensive tests for v2 endpoints
4. Deployment: Deploy backend v2 endpoints
5. Verification: Test end-to-end with web app
6. Deprecation: Mark v1 APIs as deprecated (keep for mobile app)

Next Steps

1. Fix JWT service to use proper crypto library
2. Complete backend v2 endpoint implementations
3. Update web app services to use HttpRepositoryV2 methods
4. Write tests
5. Deploy and verify