itqop
/
hubmc_essentionals
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
hubmc_essentionals/API_ENDPOINTS.md

17 KiB
Raw Permalink Blame History

HubGW API Endpoints Documentation

Полное описание всех API endpoints в HubGW с телами запросов и ответов.

Базовый URL: /api/v1

Все endpoints требуют аутентификации через заголовок X-API-Key.

Health

Префикс: /health

GET /health/

Проверка работоспособности сервиса.

Ответ:

{
  "status": "ok"
}

Homes

Префикс: /homes

PUT /homes/

Создает или обновляет дом игрока.

Тело запроса:

{
  "player_uuid": "string",
  "name": "string",
  "world": "string",
  "x": 0.0,
  "y": 0.0,
  "z": 0.0,
  "yaw": 0.0,
  "pitch": 0.0,
  "is_public": false
}

Ответ:

{
  "id": "uuid",
  "player_uuid": "string",
  "name": "string",
  "world": "string",
  "x": 0.0,
  "y": 0.0,
  "z": 0.0,
  "yaw": 0.0,
  "pitch": 0.0,
  "is_public": false,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

POST /homes/get

Получает конкретный дом игрока по имени.

Тело запроса:

{
  "player_uuid": "string",
  "name": "string"
}

Ответ:

{
  "id": "uuid",
  "player_uuid": "string",
  "name": "string",
  "world": "string",
  "x": 0.0,
  "y": 0.0,
  "z": 0.0,
  "yaw": 0.0,
  "pitch": 0.0,
  "is_public": false,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

GET /homes/{player_uuid}

Получает список всех домов игрока.

Параметры:

  • player_uuid (path) - UUID игрока

Ответ:

{
  "homes": [
    {
      "id": "uuid",
      "player_uuid": "string",
      "name": "string",
      "world": "string",
      "x": 0.0,
      "y": 0.0,
      "z": 0.0,
      "yaw": 0.0,
      "pitch": 0.0,
      "is_public": false,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1
}

Kits

Префикс: /kits

POST /kits/claim

Выдает набор (kit) игроку.

Тело запроса:

{
  "player_uuid": "uuid",
  "kit_name": "string"
}

Ответ:

{
  "success": true,
  "message": "string",
  "cooldown_remaining": 3600
}

Cooldowns

Префикс: /cooldowns

POST /cooldowns/check

Проверяет статус кулдауна для игрока.

Тело запроса:

{
  "player_uuid": "string",
  "cooldown_type": "string"
}

Ответ:

{
  "is_active": true,
  "expires_at": "2024-01-01T00:00:00Z",
  "remaining_seconds": 3600
}

POST /cooldowns/

Создает новый кулдаун для игрока.

Тело запроса:

{
  "player_uuid": "string",
  "cooldown_type": "string",
  "expires_at": "2024-01-01T00:00:00Z",
  "cooldown_seconds": 3600,
  "data": {}
}

Статус: 201 Created

Ответ:

{
  "message": "Cooldown created successfully"
}

Warps

Префикс: /warps

POST /warps/

Создает новую точку варпа.

Тело запроса:

{
  "name": "string",
  "world": "string",
  "x": 0.0,
  "y": 0.0,
  "z": 0.0,
  "yaw": 0.0,
  "pitch": 0.0,
  "is_public": true,
  "description": "string"
}

Статус: 201 Created

Ответ:

{
  "id": "uuid",
  "name": "string",
  "world": "string",
  "x": 0.0,
  "y": 0.0,
  "z": 0.0,
  "yaw": 0.0,
  "pitch": 0.0,
  "is_public": true,
  "description": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

PATCH /warps/

Обновляет существующую точку варпа.

Тело запроса:

{
  "name": "string",
  "world": "string",
  "x": 0.0,
  "y": 0.0,
  "z": 0.0,
  "yaw": 0.0,
  "pitch": 0.0,
  "is_public": true,
  "description": "string"
}

Ответ:

{
  "id": "uuid",
  "name": "string",
  "world": "string",
  "x": 0.0,
  "y": 0.0,
  "z": 0.0,
  "yaw": 0.0,
  "pitch": 0.0,
  "is_public": true,
  "description": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

DELETE /warps/

Удаляет точку варпа.

Тело запроса:

{
  "name": "string"
}

Статус: 204 No Content

POST /warps/get

Получает конкретную точку варпа по имени.

Тело запроса:

{
  "name": "string"
}

Ответ:

{
  "id": "uuid",
  "name": "string",
  "world": "string",
  "x": 0.0,
  "y": 0.0,
  "z": 0.0,
  "yaw": 0.0,
  "pitch": 0.0,
  "is_public": true,
  "description": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

POST /warps/list

Получает список точек варпа с возможностью фильтрации.

Тело запроса:

{
  "name": "string",
  "world": "string",
  "is_public": true,
  "page": 1,
  "size": 20
}

Ответ:

{
  "warps": [
    {
      "id": "uuid",
      "name": "string",
      "world": "string",
      "x": 0.0,
      "y": 0.0,
      "z": 0.0,
      "yaw": 0.0,
      "pitch": 0.0,
      "is_public": true,
      "description": "string",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 20,
  "pages": 1
}

Whitelist

Префикс: /whitelist

POST /whitelist/add

Добавляет игрока в белый список.

Тело запроса:

{
  "player_name": "string",
  "added_by": "string",
  "added_at": "2024-01-01T00:00:00Z",
  "expires_at": "2024-01-01T00:00:00Z",
  "is_active": true,
  "reason": "string"
}

Статус: 201 Created

Ответ:

{
  "id": "uuid",
  "player_name": "string",
  "added_by": "string",
  "added_at": "2024-01-01T00:00:00Z",
  "expires_at": "2024-01-01T00:00:00Z",
  "is_active": true,
  "reason": "string"
}

POST /whitelist/remove

Удаляет игрока из белого списка.

Тело запроса:

{
  "player_name": "string"
}

Статус: 204 No Content

POST /whitelist/check

Проверяет, находится ли игрок в белом списке.

Тело запроса:

{
  "player_name": "string"
}

Ответ:

{
  "is_whitelisted": true
}

GET /whitelist/

Получает список всех игроков в белом списке.

Ответ:

{
  "entries": [
    {
      "id": "uuid",
      "player_name": "string",
      "added_by": "string",
      "added_at": "2024-01-01T00:00:00Z",
      "expires_at": "2024-01-01T00:00:00Z",
      "is_active": true,
      "reason": "string"
    }
  ],
  "total": 1
}

GET /whitelist/count

Получает общее количество игроков в белом списке.

Ответ:

{
  "total": 42
}

Punishments

Префикс: /punishments

POST /punishments/

Создает новое наказание (бан/мут).

Тело запроса:

{
  "player_uuid": "string",
  "player_name": "string",
  "player_ip": "192.168.1.1",
  "punishment_type": "string",
  "reason": "string",
  "staff_uuid": "string",
  "staff_name": "string",
  "expires_at": "2024-01-01T00:00:00Z",
  "evidence_url": "string",
  "notes": "string"
}

Статус: 201 Created

Ответ:

{
  "id": "uuid",
  "player_uuid": "string",
  "player_name": "string",
  "player_ip": "192.168.1.1",
  "punishment_type": "string",
  "reason": "string",
  "staff_uuid": "string",
  "staff_name": "string",
  "expires_at": "2024-01-01T00:00:00Z",
  "is_active": true,
  "revoked_at": null,
  "revoked_by": null,
  "revoked_reason": null,
  "evidence_url": "string",
  "notes": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

POST /punishments/revoke

Отменяет наказание.

Тело запроса:

{
  "punishment_id": "uuid",
  "revoked_by": "string",
  "revoked_reason": "string"
}

Ответ:

{
  "id": "uuid",
  "player_uuid": "string",
  "player_name": "string",
  "player_ip": "192.168.1.1",
  "punishment_type": "string",
  "reason": "string",
  "staff_uuid": "string",
  "staff_name": "string",
  "expires_at": "2024-01-01T00:00:00Z",
  "is_active": false,
  "revoked_at": "2024-01-01T00:00:00Z",
  "revoked_by": "string",
  "revoked_reason": "string",
  "evidence_url": "string",
  "notes": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

POST /punishments/query

Выполняет поиск наказаний по фильтрам.

Тело запроса:

{
  "player_uuid": "string",
  "punishment_type": "string",
  "is_active": true,
  "page": 1,
  "size": 20
}

Ответ:

{
  "punishments": [
    {
      "id": "uuid",
      "player_uuid": "string",
      "player_name": "string",
      "player_ip": "192.168.1.1",
      "punishment_type": "string",
      "reason": "string",
      "staff_uuid": "string",
      "staff_name": "string",
      "expires_at": "2024-01-01T00:00:00Z",
      "is_active": true,
      "revoked_at": null,
      "revoked_by": null,
      "revoked_reason": null,
      "evidence_url": "string",
      "notes": "string",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 20,
  "pages": 1
}

GET /punishments/ban/{player_uuid}

Получает статус активного бана игрока.

Параметры:

  • player_uuid (path) - UUID игрока

Ответ:

{
  "is_banned": true,
  "punishment": {
    "id": "uuid",
    "player_uuid": "string",
    "player_name": "string",
    "player_ip": "192.168.1.1",
    "punishment_type": "ban",
    "reason": "string",
    "staff_uuid": "string",
    "staff_name": "string",
    "expires_at": "2024-01-01T00:00:00Z",
    "is_active": true,
    "revoked_at": null,
    "revoked_by": null,
    "revoked_reason": null,
    "evidence_url": "string",
    "notes": "string",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

GET /punishments/mute/{player_uuid}

Получает статус активного мута игрока.

Параметры:

  • player_uuid (path) - UUID игрока

Ответ:

{
  "is_muted": true,
  "punishment": {
    "id": "uuid",
    "player_uuid": "string",
    "player_name": "string",
    "player_ip": "192.168.1.1",
    "punishment_type": "mute",
    "reason": "string",
    "staff_uuid": "string",
    "staff_name": "string",
    "expires_at": "2024-01-01T00:00:00Z",
    "is_active": true,
    "revoked_at": null,
    "revoked_by": null,
    "revoked_reason": null,
    "evidence_url": "string",
    "notes": "string",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Audit

Префикс: /audit

POST /audit/commands

Логирует выполнение команды для аудита.

Тело запроса:

{
  "player_uuid": "uuid",
  "player_name": "string",
  "command": "string",
  "arguments": ["arg1", "arg2"],
  "server": "string",
  "timestamp": "2024-01-01T00:00:00Z"
}

Статус: 202 Accepted

Ответ:

{
  "accepted": 1
}

LuckPerms

Префикс: /luckperms

GET /luckperms/players/{uuid}

Получает информацию об игроке по UUID.

Параметры:

  • uuid (path) - UUID игрока

Ответ:

{
  "uuid": "string",
  "username": "string",
  "primary_group": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

GET /luckperms/players/username/{username}

Получает информацию об игроке по имени.

Параметры:

  • username (path) - Имя игрока

Ответ:

{
  "uuid": "string",
  "username": "string",
  "primary_group": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

GET /luckperms/groups/{name}

Получает информацию о группе по имени.

Параметры:

  • name (path) - Название группы

Ответ:

{
  "name": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

GET /luckperms/players/{uuid}/permissions

Получает список разрешений игрока.

Параметры:

  • uuid (path) - UUID игрока

Ответ:

[
  {
    "id": 1,
    "uuid": "string",
    "permission": "string",
    "value": true,
    "server": "string",
    "world": "string",
    "expiry": 1234567890,
    "contexts": "string",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
]

GET /luckperms/players/{uuid}/with-permissions

Получает информацию об игроке вместе со всеми разрешениями.

Параметры:

  • uuid (path) - UUID игрока

Ответ:

{
  "uuid": "string",
  "username": "string",
  "primary_group": "string",
  "permissions": [
    {
      "id": 1,
      "uuid": "string",
      "permission": "string",
      "value": true,
      "server": "string",
      "world": "string",
      "expiry": 1234567890,
      "contexts": "string",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

POST /luckperms/players

Создает нового игрока в LuckPerms.

Тело запроса:

{
  "username": "string",
  "primary_group": "default"
}

Статус: 201 Created

Ответ:

{
  "uuid": "string",
  "username": "string",
  "primary_group": "default",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Teleport History

Префикс: /teleport-history

POST /teleport-history/

Создает запись о телепортации в истории.

Тело запроса:

{
  "player_uuid": "string",
  "from_world": "string",
  "from_x": 0.0,
  "from_y": 0.0,
  "from_z": 0.0,
  "to_world": "string",
  "to_x": 0.0,
  "to_y": 0.0,
  "to_z": 0.0,
  "tp_type": "string",
  "target_name": "string"
}

Статус: 201 Created

Ответ:

{
  "id": "uuid",
  "player_uuid": "string",
  "from_world": "string",
  "from_x": 0.0,
  "from_y": 0.0,
  "from_z": 0.0,
  "to_world": "string",
  "to_x": 0.0,
  "to_y": 0.0,
  "to_z": 0.0,
  "tp_type": "string",
  "target_name": "string",
  "created_at": "2024-01-01T00:00:00Z"
}

GET /teleport-history/players/{player_uuid}

Получает историю телепортаций игрока.

Параметры:

  • player_uuid (path) - UUID игрока
  • limit (query) - Максимальное количество записей (по умолчанию: 100, мин: 1, макс: 1000)

Ответ:

[
  {
    "id": "uuid",
    "player_uuid": "string",
    "from_world": "string",
    "from_x": 0.0,
    "from_y": 0.0,
    "from_z": 0.0,
    "to_world": "string",
    "to_x": 0.0,
    "to_y": 0.0,
    "to_z": 0.0,
    "tp_type": "string",
    "target_name": "string",
    "created_at": "2024-01-01T00:00:00Z"
  }
]

Users

Префикс: /users

GET /users/users/{name}/game-id

Получает игровой ID пользователя по имени.

Параметры:

  • name (path) - Имя пользователя

Ответ:

{
  "game_id": "string"
}

Аутентификация

Все endpoints (кроме /health/) требуют наличия заголовка:

X-API-Key: <your-api-key>

API ключ настраивается через переменную окружения SECURITY__API_KEY.

Обработка ошибок

Все endpoints возвращают стандартные HTTP коды ошибок:

  • 400 Bad Request - некорректные данные в запросе
  • 401 Unauthorized - отсутствует или неверный API ключ
  • 404 Not Found - ресурс не найден
  • 500 Internal Server Error - внутренняя ошибка сервера

Тело ответа при ошибке содержит детальное описание проблемы.