R3944Realms/MCLTDWhitelistSystem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
65584bb8d8
MCLTDWhitelistSystem/docs/whitelist-api-en.md

7.9 KiB
Raw Blame History

Whitelist API Documentation

Base URL

https://your_host_url/api/whitelist

Authentication

All endpoints require authentication. Choose one of the following methods:

Method Example
X-API-Key header -H "X-API-Key: <token>"
X-API-TOKEN header -H "X-API-TOKEN: <token>"
Query parameter ?apiKey=<token>
Admin session cookie Browser login at /admin/login

Failure response (HTTP 403):

{"code": 403, "msg": "Permission denied: API Key is invalid or missing", "data": null}

Response Format

All endpoints return the following structure:

{
  "code": 200,
  "msg": "Success message",
  "count": 0,
  "data": {}
}
HTTP Status code Meaning
200 200 Success
200 500 Business error (e.g. player not found, RCON failure)
403 403 Authentication failure

Endpoints

1. Get Whitelist (Approved Players)

GET /api/whitelist/list

Returns player records (default: approved, status=1).

Parameters:

Name Type Required Default Description
playerName String no — Filter by player name (partial match)
page Integer no 1 Page number
size Integer no 10 Items per page
all Boolean no false When true, returns all records without pagination

Paginated query:

curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/list?page=1&size=10&playerName=Steve"

All records (no pagination):

curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/list?all=true"
Example response 
{
  "code": 200,
  "msg": "查询成功",
  "count": 42,
  "data": [
    {
      "id": 1,
      "playerName": "Steve",
      "uuid": "8667ba71b85a4004af54457a9734eed7",
      "qq": "123456789",
      "status": 1,
      "description": "I love this server",
      "createTime": "2026-06-01T12:00:00",
      "regionCode": 110000,
      "regionFullName": "北京市",
      "operatorId": 1,
      "operatorUsername": "admin",
      "operatorNickname": "Admin",
      "totalScore": 85,
      "emailActive": true
    }
  ]
}

2. Get Pending Applications

GET /api/whitelist/pending

Returns paginated list of players awaiting review (status=2).

Parameters: Same as /list (including all).

curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/pending?page=1&size=10"

3. Get Rejected Applications

GET /api/whitelist/rejected

Returns paginated list of rejected players (status=0).

Parameters: Same as /list (including all).

curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/rejected?page=1&size=10"

4. Approve Application (Add to Whitelist)

POST /api/whitelist/approve/{id}

Approves a pending player and adds them to the Minecraft server whitelist via RCON. When authenticated via API Key, the operator record will be null.

Path Parameters:

Name Type Description
id Integer Player ID

Success response:

{"code": 200, "msg": "已加入白名单", "data": null}

Error response:

{"code": 500, "msg": "操作失败，Rcon连接错误或玩家不存在", "data": null}

curl -X POST -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/approve/1"

5. Reject Application

POST /api/whitelist/reject/{id}

Rejects an application. Sets status to 0 and notifies via email.

Path Parameters: Same as approve.

curl -X POST -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/reject/1"

Success response:

{"code": 200, "msg": "已拒绝申请", "data": null}

6. Remove from Whitelist

DELETE /api/whitelist/remove/{id}

Removes a player from the Minecraft whitelist via RCON and deletes their record. An email notification is sent.

Path Parameters: Player ID.

curl -X DELETE -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/remove/1"

Success response:

{"code": 200, "msg": "已从白名单移除", "data": null}

7. Batch Approve

POST /api/whitelist/batchApprove

Approve multiple applications at once.

Request Body:

[1, 2, 3, 5]

Success response:

{"code": 200, "msg": "成功处理：4/4", "data": null}

Partial success response:

{"code": 200, "msg": "成功处理：3/4", "data": null}

curl -X POST -H "Content-Type: application/json" -H "X-API-TOKEN: <token>" \
  -d '[1,2,3]' \
  "https://whitelist.r3944realms.top/api/whitelist/batchApprove"

8. Batch Reject

POST /api/whitelist/batchReject

Reject multiple applications at once.

Request Body: Same as batchApprove ([1, 2, 3]).

curl -X POST -H "Content-Type: application/json" -H "X-API-TOKEN: <token>" \
  -d '[4,5]' \
  "https://whitelist.r3944realms.top/api/whitelist/batchReject"

Success response:

{"code": 200, "msg": "成功处理：2/2", "data": null}

9. Batch Remove

DELETE /api/whitelist/batchRemove

Remove multiple players from whitelist at once.

Request Body: [1, 2, 3]

curl -X DELETE -H "Content-Type: application/json" -H "X-API-TOKEN: <token>" \
  -d '[1,2]' \
  "https://whitelist.r3944realms.top/api/whitelist/batchRemove"

Success response:

{"code": 200, "msg": "成功移除：2/2", "data": null}

10. Whitelist Statistics

GET /api/whitelist/stats

Returns counts by status.

curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/stats"

Response:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "approved": 42,
    "pending": 5,
    "rejected": 10
  }
}

11. Check Player Whitelist Status

GET /api/whitelist/check/{playerName}

Query a player's application status by their Minecraft name.

curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/check/Steve"

Response (found):

{
  "code": 200,
  "data": {
    "exists": true,
    "status": 1,
    "playerName": "Steve",
    "qq": "12345",
    "uuid": "8667ba71b85a4004af54457a9734eed7",
    "statusText": "已通过"
  }
}

Response (not found):

{
  "code": 200,
  "data": {
    "exists": false
  }
}

Status codes:

status statusText
0 已拒绝 (Rejected)
1 已通过 (Approved)
2 待审核 (Pending)

12. Get Player Score

GET /api/whitelist/score/{id}

Returns the total exam score for a player.

curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/score/1"

Response:

{
  "code": 200,
  "data": {
    "playerId": 1,
    "totalScore": 85
  }
}

Error (not found):

{"code": 500, "msg": "玩家不存在", "data": null}

PlayerInfo Object

Field Type Description
id Integer Player ID
playerName String Minecraft username
uuid String Mojang account UUID
qq String QQ number
status Byte 0=rejected, 1=approved, 2=pending
description String Application note
createTime String Application timestamp (ISO 8601)
regionCode Long Region postal code
regionFullName String Full region name (e.g. "北京市")
operatorId Integer ID of the admin who processed
operatorUsername String Admin username
operatorNickname String Admin nickname
totalScore Integer Total exam score
emailActive Boolean Whether email is verified