168 lines
4.5 KiB
Markdown
168 lines
4.5 KiB
Markdown
# API Refactor v2.0 - Complete Redesign
|
|
|
|
## Overview
|
|
|
|
The API has been completely refactored to be **standalone and independent**. It no longer depends on bot modules and contains all necessary code within the `api/` directory.
|
|
|
|
## Changes
|
|
|
|
### ✅ Completed
|
|
|
|
1. **Cleaned root directory**:
|
|
- Moved all `.md` documentation files to `docs/archive/`
|
|
- Moved migration scripts to `scripts/`
|
|
- Root is now clean with only essential config files
|
|
|
|
2. **Created standalone API modules**:
|
|
- `api/database.py` - Complete database operations (no bot dependency)
|
|
- `api/world_loader.py` - Game world loader with data models
|
|
- `api/items.py` - Items manager
|
|
- `api/game_logic.py` - All game mechanics
|
|
- `api/main_new.py` - New standalone FastAPI application
|
|
|
|
3. **New database schema**:
|
|
- `players.id` is now the primary key (auto-increment)
|
|
- `telegram_id` is optional (nullable) for Telegram users
|
|
- `username`/`password_hash` for web users
|
|
- All foreign keys now reference `players.id` instead of `telegram_id`
|
|
|
|
4. **Simplified deployment**:
|
|
- Removed unnecessary nginx complexity
|
|
- Traefik handles all routing
|
|
- PWA serves static files via nginx (efficient for static content)
|
|
- API is completely standalone
|
|
|
|
## Migration Path
|
|
|
|
### Option 1: Fresh Start (Recommended)
|
|
|
|
**Pros**: Clean database, no migration issues
|
|
**Cons**: Loses existing Telegram user data
|
|
|
|
```bash
|
|
# 1. Stop all containers
|
|
docker compose down
|
|
|
|
# 2. Remove old database
|
|
docker volume rm echoes-of-the-ashes-postgres-data
|
|
|
|
# 3. Update files
|
|
mv api/main_new.py api/main.py
|
|
mv api/requirements_new.txt api/requirements.txt
|
|
mv Dockerfile.api.new Dockerfile.api
|
|
|
|
# 4. Rebuild and start
|
|
docker compose up -d --build
|
|
```
|
|
|
|
### Option 2: Migrate Existing Data
|
|
|
|
**Pros**: Keeps Telegram user data
|
|
**Cons**: Requires running migration script
|
|
|
|
```bash
|
|
# 1. Create migration script to:
|
|
# - Add `id` column as primary key
|
|
# - Make `telegram_id` nullable
|
|
# - Update all foreign keys
|
|
# - Backfill `id` values
|
|
|
|
# 2. Run migration
|
|
docker exec -it echoes_of_the_ashes_api python scripts/migrate_to_v2.py
|
|
|
|
# 3. Update files and rebuild
|
|
# (same as Option 1 steps 3-4)
|
|
```
|
|
|
|
## New API Structure
|
|
|
|
```
|
|
api/
|
|
├── main_new.py # Standalone FastAPI app
|
|
├── database.py # All database operations
|
|
├── world_loader.py # World data loading
|
|
├── items.py # Items management
|
|
├── game_logic.py # Game mechanics
|
|
├── internal.py # (deprecated - logic moved to main)
|
|
└── requirements_new.txt # Minimal dependencies
|
|
```
|
|
|
|
## Bot Integration
|
|
|
|
The bot will now call the API for all operations instead of directly accessing the database.
|
|
|
|
### Bot Changes Needed:
|
|
|
|
1. **Replace direct database calls** with API calls using `httpx`:
|
|
```python
|
|
# Old:
|
|
player = await get_player(telegram_id)
|
|
|
|
# New:
|
|
response = await http_client.get(
|
|
f"{API_URL}/api/internal/player/{telegram_id}",
|
|
headers={"Authorization": f"Bearer {INTERNAL_KEY}"}
|
|
)
|
|
player = response.json()
|
|
```
|
|
|
|
2. **Use internal endpoints** (protected by API key):
|
|
- `GET /api/internal/player/{telegram_id}` - Get player
|
|
- `POST /api/internal/player` - Create player
|
|
- All other game operations use public endpoints with JWT
|
|
|
|
## Environment Variables
|
|
|
|
```env
|
|
# Database
|
|
POSTGRES_USER=your_user
|
|
POSTGRES_PASSWORD=your_password
|
|
POSTGRES_DB=echoes_db
|
|
POSTGRES_HOST=echoes_of_the_ashes_db
|
|
POSTGRES_PORT=5432
|
|
|
|
# API
|
|
JWT_SECRET_KEY=your-jwt-secret-key
|
|
API_INTERNAL_KEY=your-internal-api-key
|
|
|
|
# Bot (if using)
|
|
TELEGRAM_BOT_TOKEN=your-bot-token
|
|
```
|
|
|
|
## Testing the New API
|
|
|
|
1. **Health check**:
|
|
```bash
|
|
curl https://your-domain.com/health
|
|
```
|
|
|
|
2. **Register web user**:
|
|
```bash
|
|
curl -X POST https://your-domain.com/api/auth/register \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"username":"testuser","password":"testpass"}'
|
|
```
|
|
|
|
3. **Get location**:
|
|
```bash
|
|
curl https://your-domain.com/api/game/location \
|
|
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
|
```
|
|
|
|
## Benefits
|
|
|
|
1. **Standalone** - API has zero bot dependencies
|
|
2. **Clean** - All logic in one place
|
|
3. **Testable** - Easy to test without bot infrastructure
|
|
4. **Maintainable** - Clear separation of concerns
|
|
5. **Scalable** - API and bot can scale independently
|
|
6. **Flexible** - Easy to add new clients (mobile app, etc.)
|
|
|
|
## Next Steps
|
|
|
|
1. Choose migration path (fresh start vs migrate)
|
|
2. Update and rebuild containers
|
|
3. Test web interface
|
|
4. Refactor bot to use API endpoints
|
|
5. Remove old `api/main.py` and `api/internal.py`
|