The Casino Gaming Platform exposes a RESTful API that allows the frontend application to interact with the backend services. The API is secured using JWT tokens provided by Keycloak.

Base URL

Development: http://localhost:8080
Production: https://api.casino-gaming-platform.com

Authentication

All API endpoints (except those explicitly marked as public) require authentication.

Authentication Header

Include the JWT token in the Authorization header:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA...

Obtaining Tokens

Tokens are obtained through the Keycloak authentication flow. For testing purposes, you can obtain a token using:

POST /auth/realms/lf12-realm/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&client_id=casino-frontend&username=testuser&password=testpassword

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

200 OK: Successful request
201 Created: Resource created successfully
400 Bad Request: Invalid request parameters
401 Unauthorized: Authentication required
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
500 Internal Server Error: Server error

Error responses follow this structure:

{
  "timestamp": "2023-07-21T15:45:30.123Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid amount",
  "path": "/api/deposits/create-session"
}

Rate Limiting

API requests are rate-limited to prevent abuse:

Standard users: 100 requests per minute
VIP users: 300 requests per minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1630000000

API Endpoints

Health Check

Get API Health Status

GET /api/health

Public endpoint that returns the status of the API.

Response:

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP"
    },
    "keycloak": {
      "status": "UP"
    }
  }
}

User Endpoints

Get Current User

GET /api/users/me

Returns the profile of the currently authenticated user.

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "player1",
  "email": "player1@example.com",
  "balance": 15000,
  "createdAt": "2023-01-15T10:30:45Z",
  "roles": ["user"],
  "preferences": {
    "theme": "dark",
    "notifications": true
  }
}

Get User by ID

GET /api/users/{id}

Returns a user by their ID. Requires admin role.

Parameters:

id: User ID (UUID)

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "player1",
  "email": "player1@example.com",
  "balance": 15000,
  "createdAt": "2023-01-15T10:30:45Z",
  "roles": ["user"],
  "preferences": {
    "theme": "dark",
    "notifications": true
  }
}

Create User

POST /api/users

Creates a new user account. Usually called during registration process.

Request Body:

{
  "username": "newplayer",
  "email": "newplayer@example.com",
  "password": "SecurePassword123"
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "username": "newplayer",
  "email": "newplayer@example.com",
  "balance": 1000,
  "createdAt": "2023-07-21T15:45:30Z",
  "roles": ["user"]
}

Update User Preferences

PUT /api/users/{id}/preferences

Updates a user's preferences.

Parameters:

id: User ID (UUID)

Request Body:

{
  "theme": "light",
  "notifications": false
}

Response:

{
  "theme": "light",
  "notifications": false
}

Deposit Endpoints

Create Payment Session

POST /api/deposits/create-session

Creates a new Stripe payment session for depositing funds.

Request Body:

{
  "amount": 1000
}

Response:

{
  "sessionId": "cs_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "url": "https://checkout.stripe.com/pay/cs_test_a1b2c3d4..."
}

Verify Payment

POST /api/deposits/verify

Verifies a completed payment session. Usually called after successful redirect from Stripe.

Request Body:

{
  "sessionId": "cs_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
}

Response:

{
  "verified": true,
  "amount": 1000,
  "newBalance": 16000
}

Transaction Endpoints

Get User Transactions

GET /api/transactions?userId={userId}&type={type}&page={page}&size={size}

Retrieves a user's transaction history.

Parameters:

userId: User ID (UUID)
type: (Optional) Transaction type (DEPOSIT, BET, WIN, BONUS, REFUND)
page: (Optional) Page number, defaults to 0
size: (Optional) Page size, defaults to 20

Response:

{
  "content": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "type": "DEPOSIT",
      "amount": 1000,
      "previousBalance": 15000,
      "newBalance": 16000,
      "timestamp": "2023-07-21T15:45:30Z",
      "referenceId": "cs_test_a1b2c3d4...",
      "status": "COMPLETED"
    },
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d480",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "type": "BET",
      "amount": -500,
      "previousBalance": 16000,
      "newBalance": 15500,
      "timestamp": "2023-07-21T15:48:12Z",
      "referenceId": "BLACKJACK_1234",
      "status": "COMPLETED"
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 20,
    "totalElements": 143,
    "totalPages": 8
  }
}

Game Endpoints

Get Available Games

GET /api/games

Retrieves the list of available games.

Response:

[
  {
    "id": "poker",
    "name": "Poker",
    "image": "/public/poker.webp",
    "description": "Texas Hold'em Poker against AI opponents",
    "minBet": 100,
    "maxBet": 10000,
    "available": true
  },
  {
    "id": "blackjack",
    "name": "Blackjack",
    "image": "/public/blackjack.webp",
    "description": "Classic casino card game, aim for 21",
    "minBet": 50,
    "maxBet": 5000,
    "available": true
  }
]

Get Game Details

GET /api/games/{id}

Retrieves detailed information about a specific game.

Parameters:

id: Game ID

Response:

{
  "id": "poker",
  "name": "Poker",
  "image": "/public/poker.webp",
  "description": "Texas Hold'em Poker against AI opponents",
  "rules": "Standard Texas Hold'em rules apply. Each player...",
  "minBet": 100,
  "maxBet": 10000,
  "available": true,
  "variants": ["texas-holdem", "five-card-draw"],
  "features": ["ai-opponents", "tournament-mode"],
  "stats": {
    "playCount": 15432,
    "averageBet": 350,
    "biggestWin": 25000
  }
}

Start Game Session

POST /api/games/{id}/sessions

Starts a new game session.

Parameters:

id: Game ID

Request Body:

{
  "betAmount": 200,
  "variant": "texas-holdem"
}

Response:

{
  "sessionId": "g47ac10b-58cc-4372-a567-0e02b2c3d479",
  "gameId": "poker",
  "variant": "texas-holdem",
  "initialBet": 200,
  "timestamp": "2023-07-21T15:48:12Z",
  "initialState": {
    "deck": "encrypted_deck_state",
    "players": 4,
    "position": 2
  }
}

Admin Endpoints

System Status

GET /api/admin/system/status

Returns system status information. Requires admin role.

Response:

{
  "activeSessions": 143,
  "registeredUsers": 2567,
  "activeGames": {
    "poker": 45,
    "blackjack": 67,
    "slots": 31
  },
  "systemLoad": 0.42,
  "databaseSize": "1.3 GB",
  "uptime": "27d 14h 12m"
}

Webhooks

Stripe Payment Webhook

POST /api/webhooks/stripe

Webhook endpoint for Stripe payment notifications. This endpoint is called by Stripe when payment events occur.

Request Body:

Stripe event object. See Stripe API documentation for details.

Response:

{
  "received": true
}

API Versioning

The API version is specified in the URL:

/api/v1/users

Currently, only v1 is supported.

The API supports CORS for the following origins:

http://localhost:4200 (development)
https://casino-gaming-platform.com (production)

API Clients

REST Clients

Sample HTTP requests for testing are available in the repository:

requests/getBearerToken.http - Obtaining auth token
requests/healthCheck.http - Health check endpoint
requests/user.http - User-related endpoints

Swagger UI

A Swagger UI is available for interactive API exploration:

Development: http://localhost:8080/swagger
Production: https://api.casino-gaming-platform.com/swagger

API Documentation

Overview

Base URL

Authentication

Authentication Header

Obtaining Tokens

Error Handling

Rate Limiting

API Endpoints

Health Check

Get API Health Status

User Endpoints

Get Current User

Get User by ID

Create User

Update User Preferences

Deposit Endpoints

Create Payment Session

Verify Payment

Transaction Endpoints

Get User Transactions

Game Endpoints

Get Available Games

Get Game Details

Start Game Session

Admin Endpoints

System Status

Webhooks

Stripe Payment Webhook

API Versioning

Cross-Origin Resource Sharing (CORS)

API Clients

REST Clients

Swagger UI