Auction Scoreboard API Documentation

Overview

The Auction Scoreboard API is a RESTful web service built with Spring Boot that manages cricket auction operations. It handles player bidding, team scoreboard tracking, and auction state management.

Base URL

http://localhost:8080/api/auction

Endpoints

1. Get Auction Scoreboard

Retrieves the current auction scoreboard with all teams and their details.

Endpoint:

GET /api/auction/scoreboard

Response:

{
  "1": {
    "teamId": 1,
    "teamName": "Mumbai Indians",
    "totalSpent": 50000000,
    "remainingBudget": 50000000,
    "playersCount": 15,
    "players": [...]
  },
  "2": {
    "teamId": 2,
    "teamName": "Chennai Super Kings",
    "totalSpent": 48000000,
    "remainingBudget": 52000000,
    "playersCount": 14,
    "players": [...]
  }
}

Status Codes:

• 200 OK - Successfully retrieved scoreboard

---

2. Fetch Next Player

Retrieves the next player to be auctioned based on the category.

Endpoint:

GET /api/auction/fetchNext
Content-Type: application/json

Request Body:

{
  "category": "BATSMAN"
}

Supported Categories:

• BATSMAN
• BOWLER
• ALL-ROUNDER
• WICKET-KEEPER

Response:

{
  "playerId": 1,
  "playerName": "Virat Kohli",
  "category": "BATSMAN",
  "basePrice": 2000000,
  "country": "INDIA",
  "status": "AVAILABLE"
}

Status Codes:

• 200 OK - Player fetched successfully
• 400 BAD REQUEST - Invalid category provided

---

3. Save Player Bid

Records a bid for a player by a team during the auction.

Endpoint:

POST /api/auction/player/bid
Content-Type: application/json

Request Body:

{
  "playerId": 1,
  "teamId": 5,
  "price": 15000000
}

Validation Rules:

• playerId - Required (Integer)
• teamId - Required (Integer)
• price - Required (Integer, must be > 0)

Response (Success):

{
  "status": "SUCCESS",
  "message": "Player bid saved successfully",
  "playerId": 1
}

Response (Error - Missing Fields):

{
  "status": "ERROR",
  "message": "playerId, teamId and price are required"
}

Response (Error - Invalid Price):

{
  "status": "ERROR",
  "message": "price must be greater than 0"
}

Status Codes:

• 200 OK - Bid saved successfully
• 400 BAD REQUEST - Validation failed

---

4. Mark Player as Unsold

Marks a player as unsold if no team successfully bids for them.

Endpoint:

POST /api/auction/player/unsold
Content-Type: application/json

Request Body:

{
  "playerId": 1
}

Validation Rules:

• playerId - Required (Integer)

Response (Success):

{
  "status": "SUCCESS",
  "message": "Player marked as UNSOLD",
  "playerId": 1
}

Response (Error - Missing Field):

{
  "status": "FAILED",
  "message": "playerId is required"
}

Status Codes:

• 200 OK - Player marked as unsold
• 400 BAD REQUEST - playerId not provided

---

5. Get Team Player Details

Retrieves detailed information about all teams and their players.

Endpoint:

GET /api/auction/teamDetails

Response:

{
  "1": {
    "teamId": 1,
    "teamName": "Mumbai Indians",
    "budget": 100000000,
    "spent": 50000000,
    "remaining": 50000000,
    "players": [
      {
        "playerId": 1,
        "playerName": "Virat Kohli",
        "category": "BATSMAN",
        "purchasePrice": 15000000
      }
    ]
  }
}

Status Codes:

• 200 OK - Team details retrieved successfully

---

Data Models

TeamDetailsDto

{
  "teamId": Long,
  "teamName": String,
  "totalSpent": Long,
  "remainingBudget": Long,
  "playersCount": Integer,
  "players": List<PlayerDto>
}

TeamDto

{
  "teamId": Integer,
  "teamName": String,
  "budget": Long,
  "spent": Long,
  "remaining": Long,
  "players": List<PlayerDto>
}

Player

{
  "playerId": Integer,
  "playerName": String,
  "category": String,
  "basePrice": Long,
  "country": String,
  "status": String
}

---

Error Handling

All error responses follow a consistent format:

{
  "status": "ERROR|FAILED",
  "message": "Descriptive error message",
  "details": "Additional details (optional)"
}

Common Error Codes

Error	Status Code	Message
Missing Required Fields	400	playerId, teamId and price are required
Invalid Price	400	price must be greater than 0
Player Not Found	404	Player not found with ID: {playerId}
Team Not Found	404	Team not found with ID: {teamId}
Insufficient Budget	400	Team does not have sufficient budget
Internal Server Error	500	An unexpected error occurred

---

Usage Examples

Example 1: Get Scoreboard

curl -X GET http://localhost:8080/api/auction/scoreboard \
  -H "Content-Type: application/json"

Example 2: Fetch Next Player

curl -X GET http://localhost:8080/api/auction/fetchNext \
  -H "Content-Type: application/json" \
  -d '{"category": "BATSMAN"}'

Example 3: Place a Bid

curl -X POST http://localhost:8080/api/auction/player/bid \
  -H "Content-Type: application/json" \
  -d '{
    "playerId": 1,
    "teamId": 5,
    "price": 15000000
  }'

Example 4: Mark Player Unsold

curl -X POST http://localhost:8080/api/auction/player/unsold \
  -H "Content-Type: application/json" \
  -d '{"playerId": 1}'

Example 5: Get Team Details

curl -X GET http://localhost:8080/api/auction/teamDetails \
  -H "Content-Type: application/json"

---

Architecture

AuctionScoreboardController
        ↓
AuctionScoreboardService
        ↓
Repository Layer (JPA)
        ↓
Database (PostgreSQL/MySQL)

Key Features

✅ Real-time auction scoreboard tracking
✅ Team budget management
✅ Player bidding system
✅ Category-based player queuing
✅ Unsold player tracking
✅ Comprehensive input validation
✅ RESTful API design
✅ JSON request/response format

---

Dependencies

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

---

Setup & Installation

1. Clone the repository

   git clone <repository-url>

2. Navigate to project directory

   cd auction-scoreboard

3. Build the project

   mvn clean build

4. Run the application

   mvn spring-boot:run

5. Access the API

   http://localhost:8080/api/auction
   

---

Configuration

Update application.properties or application.yml:

server.port=8080
spring.application.name=auction-scoreboard
spring.jpa.hibernate.ddl-auto=update
spring.datasource.url=jdbc:mysql://localhost:3306/auction_db
spring.datasource.username=root
spring.datasource.password=password

---

Future Enhancements

• 🔄 Real-time WebSocket updates
• 📊 Auction analytics dashboard
• 🔐 User authentication & authorization
• 📱 Mobile app integration
• 🌐 Multi-language support
• 📧 Email notifications

---

License

This project is licensed under the MIT License.

---

Support

For issues or questions, please contact: support@auction-scoreboard.com

---

Last Updated: January 23, 2026
Version: 1.0.0