Spaces:
Sleeping
Sleeping
|
Download API_DOCUMENTATION.md from Anil1515/chess-baackend: direct link, hf CLI and curl.
- Browser
- Download file 12.7 kB
-
https://huggingface.co/spaces/Anil1515/chess-baackend/resolve/main/API_DOCUMENTATION.md
- Command line
-
hf download hf://spaces/Anil1515/chess-baackend/API_DOCUMENTATION.md
-
curl -L -o API_DOCUMENTATION.md https://huggingface.co/spaces/Anil1515/chess-baackend/resolve/main/API_DOCUMENTATION.md
12.7 kB
🌐 Ludo Game - API Documentation
Base URL
Local: http://localhost:8000
Production: https://api.ludo-game.com (example)
Authentication
Currently using player_id as identifier (no auth required for MVP)
Future: JWT token-based authentication
📡 REST API Endpoints
Health & Status
✅ Health Check
GET /health
Response (200 OK):
{
"status": "ok",
"timestamp": "2026-05-14T10:30:00Z",
"version": "1.0.0"
}
🎮 Game Rooms
1️⃣ Create Room
POST /api/rooms/create
Request Body:
{
"name": "Play with friends",
"creator_id": "player_123",
"max_players": 4,
"difficulty": "medium",
"is_private": false,
"password": "optional"
}
Response (201 Created):
{
"room_id": "room_abc123",
"name": "Play with friends",
"creator_id": "player_123",
"max_players": 4,
"current_players": 1,
"difficulty": "medium",
"is_private": false,
"status": "waiting",
"created_at": "2026-05-14T10:30:00Z",
"players": [
{
"player_id": "player_123",
"name": "John",
"is_ready": false,
"joined_at": "2026-05-14T10:30:00Z"
}
]
}
Errors:
{
"detail": "Room name is required",
"status_code": 400
}
2️⃣ Join Room
POST /api/rooms/{room_id}/join
Request Body:
{
"player_id": "player_456",
"player_name": "Alice",
"password": "optional_if_private"
}
Response (200 OK):
{
"room_id": "room_abc123",
"players": [
{
"player_id": "player_123",
"name": "John",
"color": "red",
"is_ready": false
},
{
"player_id": "player_456",
"name": "Alice",
"color": "green",
"is_ready": false
}
],
"game_state": {
"current_turn": "player_123",
"status": "waiting",
"dice_value": null
}
}
Errors:
{
"detail": "Room is full",
"status_code": 400
}
3️⃣ Get Available Rooms
GET /api/rooms?difficulty=medium&is_private=false&page=1&limit=10
Query Parameters:
difficulty: (optional) "easy", "medium", "hard"is_private: (optional) true/falsepage: (optional) default: 1limit: (optional) default: 10
Response (200 OK):
{
"total": 25,
"page": 1,
"limit": 10,
"rooms": [
{
"room_id": "room_abc123",
"name": "Play with friends",
"current_players": 2,
"max_players": 4,
"difficulty": "medium",
"is_private": false,
"status": "waiting",
"created_at": "2026-05-14T10:30:00Z"
},
{
"room_id": "room_xyz789",
"name": "Weekend Game",
"current_players": 3,
"max_players": 4,
"difficulty": "hard",
"is_private": false,
"status": "in_progress",
"created_at": "2026-05-14T09:15:00Z"
}
]
}
4️⃣ Get Room Details
GET /api/rooms/{room_id}
Response (200 OK):
{
"room_id": "room_abc123",
"name": "Play with friends",
"creator_id": "player_123",
"max_players": 4,
"current_players": 2,
"difficulty": "medium",
"status": "waiting",
"players": [
{
"player_id": "player_123",
"name": "John",
"color": "red",
"is_ready": true,
"score": 0
},
{
"player_id": "player_456",
"name": "Alice",
"color": "green",
"is_ready": false,
"score": 0
}
],
"game_state": {
"current_turn": "player_123",
"dice_value": null,
"board_state": {}
},
"created_at": "2026-05-14T10:30:00Z"
}
5️⃣ Leave Room
POST /api/rooms/{room_id}/leave
Request Body:
{
"player_id": "player_456"
}
Response (200 OK):
{
"message": "Player left room successfully",
"room_id": "room_abc123",
"remaining_players": 1
}
6️⃣ Start Game
POST /api/rooms/{room_id}/start
Request Body:
{
"creator_id": "player_123"
}
Response (200 OK):
{
"room_id": "room_abc123",
"status": "in_progress",
"game_id": "game_xyz789",
"players": [
{
"player_id": "player_123",
"name": "John",
"color": "red",
"tokens": [...]
},
{
"player_id": "player_456",
"name": "Alice",
"color": "green",
"tokens": [...]
}
],
"started_at": "2026-05-14T10:35:00Z"
}
Errors:
{
"detail": "Only room creator can start game",
"status_code": 403
}
👤 Player & Statistics
7️⃣ Get Player Stats
GET /api/players/{player_id}/stats
Response (200 OK):
{
"player_id": "player_123",
"player_name": "John",
"total_games": 25,
"total_wins": 12,
"total_losses": 13,
"win_percentage": 48.0,
"current_rating": 1250,
"rating_change": "+50",
"average_game_duration": 1200,
"tokens_killed": 45,
"tokens_lost": 38,
"total_dice_rolls": 230,
"last_played": "2026-05-14T08:00:00Z",
"account_created": "2026-01-15T10:00:00Z"
}
8️⃣ Get Leaderboard
GET /api/leaderboard?timeframe=all_time&limit=100&page=1
Query Parameters:
timeframe: "all_time", "monthly", "weekly" (default: "all_time")limit: default: 100, max: 500page: default: 1
Response (200 OK):
{
"timeframe": "all_time",
"total_players": 5432,
"page": 1,
"limit": 100,
"leaderboard": [
{
"rank": 1,
"player_id": "player_001",
"player_name": "Pro Gamer",
"rating": 2500,
"wins": 450,
"games": 500,
"win_percentage": 90.0,
"last_updated": "2026-05-14T10:00:00Z"
},
{
"rank": 2,
"player_id": "player_002",
"player_name": "Strategy Master",
"rating": 2480,
"wins": 445,
"games": 500,
"win_percentage": 89.0,
"last_updated": "2026-05-14T09:45:00Z"
}
]
}
9️⃣ Get Friend Rankings
GET /api/players/{player_id}/friends/ranking
Response (200 OK):
{
"your_rank": 5,
"your_rating": 1550,
"friends": [
{
"rank": 1,
"player_id": "friend_001",
"name": "Alice",
"rating": 1750,
"wins": 50,
"games": 65,
"is_online": true
},
{
"rank": 2,
"player_id": "friend_002",
"name": "Bob",
"rating": 1650,
"wins": 45,
"games": 60,
"is_online": false
}
]
}
🎲 Game Management
🔟 Get Game History
GET /api/games/history/{player_id}?limit=20&offset=0
Response (200 OK):
{
"total_games": 128,
"games": [
{
"game_id": "game_123",
"opponent_names": ["Alice", "Bob"],
"result": "won",
"duration": 1200,
"date": "2026-05-14T08:00:00Z",
"rating_change": "+25"
},
{
"game_id": "game_122",
"opponent_names": ["Charlie"],
"result": "lost",
"duration": 900,
"date": "2026-05-14T07:00:00Z",
"rating_change": "-10"
}
]
}
🔌 WebSocket Events
Connection
// Connect to WebSocket
ws = new WebSocket('ws://localhost:8000/ws/{player_id}/{room_id}')
📤 Client → Server Events
1. Join Room (after connection)
{
"event": "join_room",
"data": {
"room_id": "room_abc123",
"player_id": "player_123",
"player_name": "John"
}
}
2. Ready (player ready to start)
{
"event": "ready",
"data": {
"room_id": "room_abc123",
"player_id": "player_123",
"is_ready": true
}
}
3. Roll Dice
{
"event": "roll_dice",
"data": {
"room_id": "room_abc123",
"player_id": "player_123"
}
}
4. Move Token
{
"event": "move_token",
"data": {
"room_id": "room_abc123",
"player_id": "player_123",
"token_id": 0,
"new_position": 5
}
}
5. Chat Message
{
"event": "chat",
"data": {
"room_id": "room_abc123",
"player_id": "player_123",
"message": "Good luck!",
"emoji": "🎲"
}
}
6. Surrender/Leave Game
{
"event": "surrender",
"data": {
"room_id": "room_abc123",
"player_id": "player_123"
}
}
📥 Server → Client Events
1. Game State Update
{
"event": "game_state",
"data": {
"current_turn": "player_123",
"current_player_name": "John",
"dice_value": 4,
"game_status": "in_progress",
"players": [
{
"player_id": "player_123",
"name": "John",
"color": "red",
"tokens": [
{"token_id": 0, "position": 12},
{"token_id": 1, "position": -1},
{"token_id": 2, "position": -1},
{"token_id": 3, "position": -1}
],
"score": 1
}
]
}
}
2. Dice Roll Result
{
"event": "dice_rolled",
"data": {
"player_id": "player_123",
"dice_value": 6,
"extra_roll": true,
"timestamp": "2026-05-14T10:35:15Z"
}
}
3. Token Moved
{
"event": "token_moved",
"data": {
"player_id": "player_123",
"token_id": 0,
"from_position": 12,
"to_position": 16,
"killed_opponent": false,
"killed_opponent_token": null
}
}
4. Token Killed
{
"event": "token_killed",
"data": {
"attacker_id": "player_123",
"attacker_name": "John",
"attacker_color": "red",
"victim_id": "player_456",
"victim_name": "Alice",
"victim_color": "green",
"position": 16
}
}
5. Player Won
{
"event": "game_over",
"data": {
"winner_id": "player_123",
"winner_name": "John",
"winner_color": "red",
"ranking": [
{"position": 1, "player_id": "player_123", "player_name": "John"},
{"position": 2, "player_id": "player_456", "player_name": "Alice"},
{"position": 3, "player_id": "player_789", "player_name": "Bob"}
],
"game_duration": 1200,
"rating_changes": {
"player_123": "+50",
"player_456": "-20",
"player_789": "-30"
}
}
}
6. Chat Message Received
{
"event": "chat_message",
"data": {
"player_id": "player_456",
"player_name": "Alice",
"message": "Nice move!",
"emoji": "👍",
"timestamp": "2026-05-14T10:35:20Z"
}
}
7. Player Joined
{
"event": "player_joined",
"data": {
"player_id": "player_789",
"player_name": "Bob",
"player_color": "yellow",
"current_players": 3
}
}
8. Player Left
{
"event": "player_left",
"data": {
"player_id": "player_789",
"player_name": "Bob",
"remaining_players": 2
}
}
9. Connection Error
{
"event": "error",
"data": {
"code": "INVALID_MOVE",
"message": "Token cannot move to that position",
"details": {
"reason": "Position is occupied by your own token"
}
}
}
🔐 Error Responses
400 Bad Request
{
"detail": "Invalid request parameters",
"status_code": 400,
"error_code": "INVALID_REQUEST"
}
401 Unauthorized
{
"detail": "Authentication required",
"status_code": 401,
"error_code": "AUTH_REQUIRED"
}
403 Forbidden
{
"detail": "You do not have permission to perform this action",
"status_code": 403,
"error_code": "FORBIDDEN"
}
404 Not Found
{
"detail": "Room not found",
"status_code": 404,
"error_code": "NOT_FOUND"
}
409 Conflict
{
"detail": "Room is already full",
"status_code": 409,
"error_code": "ROOM_FULL"
}
500 Internal Server Error
{
"detail": "An unexpected error occurred",
"status_code": 500,
"error_code": "INTERNAL_ERROR"
}
📚 Testing with cURL
Create a Room
curl -X POST http://localhost:8000/api/rooms/create \
-H "Content-Type: application/json" \
-d '{
"name": "Test Game",
"creator_id": "player_123",
"max_players": 4,
"difficulty": "medium",
"is_private": false
}'
Join Room
curl -X POST http://localhost:8000/api/rooms/room_abc123/join \
-H "Content-Type: application/json" \
-d '{
"player_id": "player_456",
"player_name": "Alice"
}'
Get Leaderboard
curl http://localhost:8000/api/leaderboard?timeframe=all_time&limit=10
Get Player Stats
curl http://localhost:8000/api/players/player_123/stats
🔄 Rate Limiting
- REST API: 1000 requests per hour per IP
- WebSocket: Unlimited (server-side validation)
Last Updated: May 14, 2026 API Version: 1.0.0 Status: 🟢 Production Ready