dotcom-arcade/docs/06-api-reference/README.md

API Reference Documentation

Complete REST API reference for Flashpoint Web backend service.

Base URL

Development: http://localhost:3100/api

Production: Configure via DOMAIN environment variable

Authentication

Most endpoints require JWT authentication. Include the access token in the Authorization header:

Authorization: Bearer <access_token>

Tokens are obtained via the /api/auth/login or /api/auth/register endpoints.

Response Format

All responses are in JSON format with consistent structure:

Success Response

{
  "data": { ... },
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1234,
    "totalPages": 25
  }
}

Error Response

{
  "error": {
    "code": 400,
    "message": "Validation error: username must be at least 3 characters"
  }
}

HTTP Status Codes

• 200 OK - Request successful
• 201 Created - Resource created successfully
• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Missing or invalid authentication token
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 409 Conflict - Resource already exists
• 500 Internal Server Error - Server error

Rate Limiting

Configurable via RATE_LIMIT_* environment variables. Default: 100 requests per 15 minutes.

Rate limit headers included in responses:

• X-RateLimit-Limit: Maximum requests per window
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Time when rate limit resets (Unix timestamp)

API Endpoints by Category

Authentication

• POST /api/auth/login
• POST /api/auth/register
• POST /api/auth/refresh
• POST /api/auth/logout
• GET /api/auth/me

Games

• GET /api/games
• GET /api/games/filter-options
• GET /api/games/random
• GET /api/games/:id
• GET /api/games/:id/launch
• GET /api/games/:id/related

Users

• GET /api/users
• GET /api/users/:id
• POST /api/users
• PATCH /api/users/:id
• DELETE /api/users/:id
• POST /api/users/:id/change-password
• GET /api/users/me/settings
• PATCH /api/users/me/settings

Roles & Permissions

• GET /api/roles
• GET /api/roles/permissions
• GET /api/roles/:id
• POST /api/roles
• PATCH /api/roles/:id
• PUT /api/roles/:id/permissions
• DELETE /api/roles/:id

Playlists

• GET /api/playlists
• GET /api/playlists/:id
• POST /api/playlists
• POST /api/playlists/:id/games
• DELETE /api/playlists/:id/games
• DELETE /api/playlists/:id

Play Tracking

• POST /api/play/start
• POST /api/play/end
• GET /api/play/stats
• GET /api/play/game-stats
• GET /api/play/history
• GET /api/play/top-games
• GET /api/play/activity-over-time
• GET /api/play/games-distribution

Platforms & Tags

• GET /api/platforms
• GET /api/tags

Complete Examples

See Request & Response Examples for complete workflow examples including:

• User registration and login flow
• Game search with filters
• Game launch workflow
• Play session tracking
• Playlist management
• Role-based access control examples

SDK Examples

See individual endpoint documentation for code examples in:

• curl (command line)
• JavaScript/TypeScript (axios)
• Python (requests)
• Go (net/http)

Versioning

API version is included in response headers: X-API-Version: 1.0.0

Breaking changes will increment major version number.

Support

For issues or questions:

• GitHub Issues: flashpoint-web/issues
• Documentation: docs/README.md