GoJo Tool API

GoJo Tool is a RESTful API system designed for managing games and processing game events. The system provides secure endpoints for game creation, management, and real-time event processing with message queue integration.

All API endpoints require Bearer token authentication. Include the token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Create a New Game

POST /api/games

Request Body:

{
    "title": "Game Title (required)",
    "description": "Game Description (optional)"
}

Response:

{
    "id": 1,
    "uuid": "game-uuid-here",
    "title": "Game Title",
    "description": "Game Description",
    "secret": "game-secret-for-signing",
    "created_at": "2024-01-01 12:00:00",
    "updated_at": "2024-01-01 12:00:00"
}

---

Get Your Games

GET /api/games

Response:

{
    "games": [
        {
            "uuid": "game-uuid-here",
            "title": "Game Title",
            "description": "Game Description",
            "secret": "game-secret-for-signing",
            "created_at": "2024-01-01 12:00:00",
            "updated_at": "2024-01-01 12:00:00"
        }
    ]
}

Get Leaderboard

GET /api/leaderboard

Query Parameters:

• game_uuid (required) - UUID of the game
• page (optional) - Page number for pagination (default: 1)
• perPage (optional) - Items per page, max 100 (default: 10)
• sort (optional) - Sort order: ASC or DESC (default: DESC)

Example Request:

GET /api/leaderboard?game_uuid=your-game-uuid&page=1&perPage=20&sort=DESC

Response:

{
    "success": true,
    "data": [
        {
            "id": 1,
            "game_uuid": "your-game-uuid",
            "player_uuid": "player-123",
            "player_title": "Player Name",
            "score": 1500,
            "created_at": "2024-01-01 12:00:00",
            "updated_at": "2024-01-01 12:30:00"
        }
    ],
    "pagination": {
        "page": 1,
        "perPage": 20,
        "total": 100,
        "totalPages": 5
    }
}

Send Game Event

POST /api/events

Request Body:

{
    "game_uuid": "your-game-uuid",
    "player_uuid": "unique-player-identifier",
    "timestamp": 1640995200,
    "sign": "md5-signature",
    "event_type": "player_score",
    "event_data": {
        "score": 1500
    }
}

Response:

{
    "success": true,
    "message": "Event processed successfully"
}

Events must be signed using MD5 hash for security. The signature is calculated as:

const signature = md5(game_uuid + player_uuid + timestamp + game_secret);

Example in JavaScript:

const crypto = require('crypto');

function generateSignature(gameUuid, playerUuid, timestamp, gameSecret) {
    const data = gameUuid + playerUuid + timestamp + gameSecret;
    return crypto.createHash('md5').update(data).digest('hex');
}

Example in PHP:

function generateSignature($gameUuid, $playerUuid, $timestamp, $gameSecret) {
    return md5($gameUuid . $playerUuid . $timestamp . $gameSecret);
}

Complete workflow example using cURL:

1. Create a game:

curl -X POST http://your-domain/api/games \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Awesome Game", "description": "A great game"}'

2. Send an event:

curl -X POST http://your-domain/api/events \
  -H "Content-Type: application/json" \
  -d '{
    "game_uuid": "your-game-uuid",
    "player_uuid": "player-123",
    "timestamp": 1640995200,
    "sign": "calculated-md5-signature",
    "event_type": "player_score",
    "event_data": {"score": 100}
  }'

3. Get leaderboard:

curl -X GET "http://your-domain/api/leaderboard?game_uuid=your-game-uuid&page=1&perPage=10&sort=DESC"

The API returns standard HTTP status codes and JSON error responses:

Authentication Errors (403):

{"error": "Bearer token required"}

Validation Errors (400):

{"error": "Title is required"}

Not Found Errors (404):

{"error": "Game not found"}

Signature Errors (401):

{"error": "Invalid signature"}