NowChessSystems/bruno

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:

/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:

   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)