Players API

The Players API provides endpoints for managing player data, profiles, preferences, and game progression in PadawanForge.

Base Paths

  • /api/players/ - Player data management
  • /api/user/ - Current user operations

Player Data

List Players

GET /api/players

Query Parameters:

  • page (optional) - Page number (default: 1)
  • limit (optional) - Items per page (default: 20, max: 100)

Response:

{
  "items": [
    {
      "uuid": "player_uuid",
      "username": "PlayerName",
      "avatar": "https://...",
      "level": 5,
      "experience": 1250,
      "joinedAt": "2024-01-15T10:30:00Z",
      "lastActive": "2024-01-20T15:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Get Player by UUID

GET /api/players/[uuid]

Parameters:

  • uuid - Player’s public UUID

Response:

{
  "uuid": "player_uuid",
  "username": "PlayerName",
  "avatar": "https://...",
  "level": 5,
  "experience": 1250,
  "achievements": [
    {
      "id": "first_win",
      "name": "First Victory",
      "unlockedAt": "2024-01-15T11:00:00Z"
    }
  ],
  "stats": {
    "gamesPlayed": 45,
    "averageScore": 850,
    "bestStreak": 12,
    "totalPlayTime": "2h 30m"
  },
  "joinedAt": "2024-01-15T10:30:00Z",
  "lastActive": "2024-01-20T15:45:00Z"
}

Get Player Experience

GET /api/players/[uuid]/experience

Authentication: Required

Response:

{
  "currentLevel": 5,
  "currentExp": 1250,
  "expToNextLevel": 750,
  "totalExp": 1250,
  "expHistory": [
    {
      "amount": 50,
      "reason": "Session completed",
      "timestamp": "2024-01-20T15:45:00Z"
    }
  ]
}

Get/Update Player Profile

GET /api/players/[id]/profile
POST /api/players/[id]/profile

Authentication: Required (can only access own profile)

POST Request Body:

{
  "username": "NewUsername",
  "avatar": "https://...",
  "bio": "Player biography",
  "location": "City, Country",
  "birthday": "YYYY-MM-DD",
  "gender": "M" | "F" | "Other" | "Prefer not to say",
  "privacySettings": {
    "showEmail": false,
    "showLocation": true,
    "showStats": true
  }
}

Response:

{
  "success": true,
  "data": {
    "uuid": "player_uuid",
    "username": "NewUsername",
    "avatar": "https://...",
    "bio": "Player biography",
    "updatedAt": "2024-01-20T16:00:00Z"
  }
}

User Preferences & Settings

Get User Preferences

GET /api/user/preferences

Authentication: Required

Response:

{
  "notifications": {
    "email": true,
    "push": false,
    "gameReminders": true,
    "socialUpdates": false
  },
  "privacy": {
    "profileVisibility": "public",
    "showEmail": false,
    "showStats": true,
    "allowDirectMessages": true
  },
  "ui": {
    "theme": "dark",
    "language": "en",
    "fontSize": "medium",
    "animations": true
  },
  "gameplay": {
    "difficulty": "normal",
    "timerStyle": "countdown",
    "soundEffects": true,
    "musicVolume": 0.7
  }
}

Update User Preferences

PATCH /api/user/preferences

Authentication: Required

Request Body: (partial update supported)

{
  "ui": {
    "theme": "light",
    "fontSize": "large"
  },
  "gameplay": {
    "soundEffects": false
  }
}

Response:

{
  "success": true,
  "data": {
    "updatedFields": ["ui.theme", "ui.fontSize", "gameplay.soundEffects"],
    "updatedAt": "2024-01-20T16:15:00Z"
  }
}

Check Preferences Status

GET /api/user/preferences-check

Authentication: Required

Response:

{
  "hasPreferences": true,
  "shouldShowTutorial": false
}

User Session Management

Get Current Session

GET /api/user/session

Authentication: Required

Response:

{
  "player": {
    "uuid": "player_uuid",
    "username": "PlayerName",
    "avatar": "https://...",
    "level": 5,
    "experience": 1250,
    "email": "player@example.com",
    "provider": "google"
  },
  "session": {
    "createdAt": "2024-01-20T10:00:00Z",
    "expiresAt": "2024-01-27T10:00:00Z",
    "lastActivity": "2024-01-20T15:45:00Z"
  },
  "permissions": ["play", "chat", "upload_files"],
  "registrationCompleted": true,
  "tutorialCompleted": true
}

Reset User Data

POST /api/user/reset

Authentication: Required

Request Body:

{
  "resetType": "preferences" | "gameData" | "all",
  "confirmToken": "user_confirmation_token"
}

Response:

{
  "success": true,
  "data": {
    "resetType": "preferences",
    "resetAt": "2024-01-20T16:30:00Z",
    "affectedData": ["preferences", "settings"]
  }
}

AI Settings Management

Get AI Settings

GET /api/user/ai-settings

Authentication: Required

Response:

{
  "aiProvider": "openai",
  "apiKey": "sk-...***masked***",
  "model": "gpt-4",
  "temperature": 0.7,
  "maxTokens": 150,
  "customPrompts": {
    "npcInteraction": "You are a helpful tutor...",
    "statementGeneration": "Generate educational true/false statements..."
  },
  "isConfigured": true,
  "lastTested": "2024-01-20T14:00:00Z"
}

Update AI Settings

POST /api/user/ai-settings

Authentication: Required

Request Body:

{
  "aiProvider": "anthropic",
  "apiKey": "sk-ant-...",
  "model": "claude-3-sonnet",
  "temperature": 0.8,
  "maxTokens": 200
}

Response:

{
  "success": true,
  "data": {
    "aiProvider": "anthropic",
    "model": "claude-3-sonnet",
    "isConfigured": true,
    "updatedAt": "2024-01-20T16:45:00Z"
  }
}

Test AI Connection

POST /api/user/ai-settings/test

Authentication: Required

Response:

{
  "success": true,
  "data": {
    "connectionStatus": "success",
    "responseTime": 1250,
    "testResponse": "Test message from AI provider",
    "testedAt": "2024-01-20T17:00:00Z"
  }
}

Account Management

Delete User Account

DELETE /api/user/preferences

Authentication: Required

Request Body:

{
  "deleteType": "soft" | "hard",
  "confirmToken": "user_confirmation_token",
  "reason": "Optional deletion reason"
}

Response:

{
  "success": true,
  "data": {
    "deleteType": "soft",
    "deletedAt": "2024-01-20T17:15:00Z",
    "recoveryPeriod": "30 days",
    "recoveryToken": "recovery_token_if_soft_delete"
  }
}

Data Privacy

Privacy Controls

Players can control visibility of:

  • Email address
  • Location information
  • Game statistics and performance
  • Profile information
  • Online status
  • Achievement details

Data Segmentation

Player data is stored across multiple tables:

  • Core Identity: UUID, authentication data
  • Profile: Username, avatar, bio, location
  • Preferences: UI settings, notifications, privacy
  • Game Data: Levels, experience, achievements, statistics
  • Personal Info: Birthday, gender, sensitive information

Error Responses

Player Not Found

{
  "error": "Player not found",
  "details": "No player found with the provided UUID"
}

Insufficient Permissions

{
  "error": "Access denied",
  "details": "You can only access your own profile data"
}

Invalid Preferences

{
  "error": "Invalid preference values",
  "details": "Theme must be 'light' or 'dark'"
}

AI Configuration Error

{
  "error": "AI configuration failed",
  "details": "Invalid API key or model not accessible"
}

Rate Limits

  • Profile updates: 10 per hour
  • Preference updates: 20 per hour
  • AI settings updates: 5 per hour
  • AI connection tests: 10 per hour

Implementation Notes

  1. UUID Privacy: Public player identifiers use UUIDs, never expose internal IDs
  2. Preference Inheritance: New users inherit system defaults for all preferences
  3. Soft Deletion: Account deletion defaults to soft delete with 30-day recovery period
  4. AI Privacy: API keys are encrypted and never returned in full in responses
  5. Profile Validation: Username uniqueness enforced with case-insensitive matching
← API Overview
PadawanForge v1.4.1