150 lines
5.2 KiB
Markdown
150 lines
5.2 KiB
Markdown
# 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)
|