leaderboard-api

Leaderboard API

• Base Path: /api/v1/leaderboard
• Auth: required

Leaderboard Entry Model

• _id: string (Mongo ObjectId)
• user: string (User ID)
• product: string (Product ObjectId)
• game: string (Game ObjectId)
• score: number
• createdAt: string (ISO datetime)
• updatedAt: string (ISO datetime)
• __v: number

Example entry:

{
  "_id": "66f111111111111111111111",
  "user": "john_doe",
  "product": "66f000000000000000000001",
  "game": "66f000000000000000000101",
  "score": 1200,
  "createdAt": "2025-09-02T10:00:00.000Z",
  "updatedAt": "2025-09-02T10:00:00.000Z",
  "__v": 0
}

Get Leaderboard

• Method: GET
• Paths:
  • /api/v1/leaderboard/:productId
• Auth: required
• Query:
  • product: string (required when using the query path)
  • page: number (optional, default 1, min 1)
  • limit: number (optional, default 100, max 500)
  • count: boolean (optional, default false) — when true, returns meta.totalCount and meta.totalPages.
• Sort: By score descending, then createdAt ascending.
• Response 200: \{ data: LeaderboardEntry[], meta: \{ page, limit, totalCount?, totalPages? \} \}
  • Note: result is also included for backward compatibility and equals data.

Example 200 response:

{
  "data": [
    {
      "_id": "66f111111111111111111111",
      "user": "john_doe",
      "product": "66f000000000000000000001",
      "game": "66f000000000000000000101",
      "score": 1200,
      "createdAt": "2025-09-02T10:00:00.000Z",
      "updatedAt": "2025-09-02T10:00:00.000Z",
      "__v": 0
    }

], "meta": { "page": 1, "limit": 100, "totalCount": 42, "totalPages": 1 } }

• Errors:
  • 400: { "error": "product is required" }
  • 401: { "error": "UNAUTHORIZED", "message": "Unauthorized access not allowed" }
  • 500: { "error": "Failed to fetch leaderboard" }

Notes

• No populate: Entries are returned without populating product or game docs.
• IDs: All ObjectId fields are strings.