feat(api): add comprehensive API collection for NowChess microservices

2026-04-30 18:56:48 +02:00
parent 77e498a326
commit 3844456f0c
74 changed files with 1395 additions and 1 deletions
@@ -0,0 +1,149 @@
+# NowChess Bruno API Collection
+
+Complete API collection for all NowChess microservices.
+
+## Structure
+
+```
+bruno/
+├── collection.bru              # Collection metadata
+├── environments/               # Environment configurations
+│   ├── local.bru              # Local development (http://localhost)
+│   ├── staging.bru            # Staging (https://st.nowchess.janis-eccarius.de)
+│   └── prod.bru               # Production (https://nowchess.janis-eccarius.de)
+├── core/                       # Core service endpoints (port 8080)
+│   ├── game.bru               # Game management
+│   ├── rules.bru              # Rule validation (@InternalOnly)
+│   ├── io.bru                 # Import/Export (@InternalOnly)
+│   └── coordinator.bru        # Orchestration
+├── account/                    # Account service (port 8083)
+│   ├── account.bru            # User & bot accounts
+│   ├── challenge.bru          # Player challenges
+│   └── official-challenge.bru # Official bot challenges
+├── store/                      # Store service (port 8085)
+│   └── game.bru               # Game persistence
+├── ws/                         # WebSocket (port 8084)
+│   ├── game-ws.bru            # Game real-time updates
+│   └── user-ws.bru            # User notifications
+└── bot/                        # Bot integration
+    └── events.bru             # Bot event streaming
+```
+
+## Ingress Routing
+
+Based on `ingress-nginx` configuration:
+
+```yaml
+/api/account  → nowchess-account-active:8083
+/ws           → nowchess-ws-active:8084
+/api/store    → nowchess-store-active:8085
+/api          → nowchess-core-active:8080
+```
+
+## Environments
+
+### Local Development
+```
+baseUrl: http://localhost:8080
+accountBaseUrl: http://localhost:8083
+storeBaseUrl: http://localhost:8085
+wsBaseUrl: ws://localhost:8084
+```
+
+### Staging
+```
+baseUrl: https://st.nowchess.janis-eccarius.de/api
+wsBaseUrl: wss://st.nowchess.janis-eccarius.de/ws
+```
+
+### Production
+```
+baseUrl: https://nowchess.janis-eccarius.de/api
+wsBaseUrl: wss://nowchess.janis-eccarius.de/ws
+```
+
+## Environment Variables
+
+Set these in your Bruno environment for authentication:
+- `token`: JWT token for regular user operations
+- `adminToken`: JWT token with Admin role
+- `botToken`: Bot account JWT token
+- `internalToken`: Internal service-to-service token
+- `gameId`: Game identifier for game endpoints
+- `username`: User username for profile/challenge operations
+- `playerId`: Player ID for store operations
+- `botId`: Bot ID for bot endpoints
+- `botName`: Official bot name for challenges
+- `difficulty`: Bot difficulty 1000-2800 (ELO)
+- `color`: white/black/random for bot challenges
+
+## Security Notes
+
+From `@modules/security/src`:
+- **InternalOnly** endpoints require internal service authentication
+  - `/api/rules/*`
+  - `/io/*`
+- **@RolesAllowed** endpoints require JWT with specific roles
+  - Admin operations
+  - Authenticated user operations
+- Internal filters validate service-to-service calls
+
+## API Endpoints Summary
+
+### Public Endpoints (No Auth Required)
+- `GET /api/account/{username}` - Public profile
+- `GET /api/account/official-bots` - List official bots
+- `GET /game/{gameId}` - Game record
+- `GET /api/board/game/{gameId}` - Game state
+- `GET /api/board/game/{gameId}/moves` - Legal moves
+
+### Authenticated Endpoints (JWT Required)
+- `POST /api/account` - Register
+- `POST /api/account/login` - Login
+- `GET /api/account/me` - Current user profile
+- `POST /api/challenge/*` - Challenge operations
+- `POST /api/challenge/official/{botName}` - Challenge official bot
+- `POST /api/account/bots` - Create bot account
+- `GET /api/bot/stream/events` - Bot event stream
+- `WS /api/board/game/{gameId}/ws` - Game WebSocket
+- `WS /api/user/ws` - User notifications
+
+### Internal Endpoints (@InternalOnly)
+- `POST /api/rules/*` - Rule validation
+- `POST /io/*` - Format conversion
+- `POST /api/board/game` - Create game
+
+## Usage
+
+1. **Select Environment**: Click the environment dropdown and choose local/staging/prod
+2. **Set Variables**: Update `token`, `gameId`, `username`, etc. as needed
+3. **Send Request**: Click Send on any endpoint
+4. **WebSocket**: Use Bruno's WebSocket support or connect manually with:
+   ```bash
+   websocat wss://nowchess.janis-eccarius.de/ws/api/board/game/GAMEID/ws
+   ```
+
+## Example Workflows
+
+### Play a Game
+1. `POST /api/account` - Create user
+2. `POST /api/account/login` - Get JWT token
+3. `POST /api/challenge/official/Stockfish` - Challenge a bot
+4. Use returned `gameId` for subsequent moves
+5. `WS /api/board/game/{gameId}/ws` - Connect for real-time updates
+6. `POST /api/board/game/{gameId}/move/{uci}` - Make moves
+
+### Manage Bot Account
+1. `POST /api/account` - Create main account
+2. `POST /api/account/login` - Get token
+3. `POST /api/account/bots` - Create bot account
+4. Copy bot token from response
+5. `GET /api/bot/stream/events?botId={botId}` - Listen for game invites
+6. `POST /api/bot/game/{gameId}/move/{uci}` - Submit moves
+
+## Notes
+
+- All timestamps are ISO 8601 format
+- Move notation uses UCI (e.g., "e2e4")
+- Game IDs are auto-generated UUIDs
+- WebSocket connections auto-close on inactivity (check your server timeout)