API Documentation

DonutAPI is a plugin that you can purchase as an addon to the DonutSMP replica that provides a REST API for server statistics and leaderboards, designed to replicate the DonutSMP API.

Players can generate their own API keys using /api to retrieve player statistics (including money, kills, deaths, playtime, and more), get player information including username, rank, and current location, and access top players for various statistics.

Dependencies

All the following dependencies are present on the setup when downloaded.

Required

• PlaceholderAPI: Core dependency for retrieving player data

Optional (for full functionality)

• Vault: For economy balance
• LuckPerms: For rank information
• CoinsEngine: For shards balance
• Statz: For blocks placed/broken and mobs killed
• AJLeaderboards: For leaderboard functionality

Installation

1. Download the plugin JAR file
2. Place it in your server's plugins folder
3. Restart your server
4. Configure the plugin in plugins/DonutAPI/config.yml. Specifically the port the API runs on.

Configuration

# Port for the API server
port: 8080

# Documentation link shown when players use /api command
documentation-link: "https://api.donutsmp.net/index.html"

# Players excluded from lookup queries
# These players cannot be queried via the /v1/lookup endpoint
excluded-players:
  - "ExamplePlayer1"
  - "ExamplePlayer2"

API Endpoints

All endpoints require an API key parameter: ?key=YOUR_API_KEY

Player Stats

GET /v1/stats?username=PLAYER&key=API_KEY

Returns player statistics including:

• money
• shards
• kills
• deaths
• playtime
• placed_blocks
• broken_blocks
• mobs_killed
• money_spent_on_shop
• money_made_from_sell

Response

200

{
  "status": 200,
  "result": {
    "money": "17714",
    "shards": "104",
    "kills": "4",
    "deaths": "18",
    "playtime": "25111986",
    "placed_blocks": "28",
    "broken_blocks": "151",
    "mobs_killed": "30",
    "money_spent_on_shop": "2100",
    "money_made_from_sell": "14815"
  }
}

Player Lookup

GET /v1/lookup?username=PLAYER&key=API_KEY

Returns player information including username, rank, and location. Note: Player must be online.

Response

200

{
  "status": 200,
  "result": {
    "username": "Atomatrix",
    "rank": "default",
    "location": "overworld"
  }
}

503

{
  "status": 503,
  "reason": "This user is not currently online."
}

404

{
  "status": 403,
  "error": "This player is excluded from lookup queries"
}

Leaderboard

GET /v1/leaderboards/{type}/{page}?key=API_KEY

Returns the leaderboards for the whole server

Available types:

• money - Top players by balance
• shards - Top players by shards
• kills - Top players by kills
• deaths - Most deaths
• playtime - Most playtime
• placedblocks - Most blocks placed
• brokenblocks - Most blocks broken
• mobskilled - Most mobs killed
• shop - Most money spent in shop
• sell - Most money made from selling

Pages show 10 entries each (page 1 = ranks 1-10, page 2 = ranks 11-20, etc.)

Response

200

{
  "status": 200,
  "result": [
    {
      "username": "Player1",
      "uuid": "7acdc84f-6e89-474e-9b87-71f375270cc9",
      "value": "21230"
    },
    {
      "username": "Player2",
      "uuid": "5ef684ca-2a4c-4b15-b0a1-88f2c83ece61",
      "value": "19870"
    }
  ]
}