itqop
/
hubmc-datagw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
hubmc-datagw/API_ENDPOINTS.md

20 KiB
Raw 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,
  "max_homes": 5
}

Параметры:

  • max_homes (optional) - Максимальное количество домов для игрока. Если указан, проверяется лимит при создании нового дома.

Ответ:

{
  "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"
}

Ошибки:

  • 409 Conflict - Лимит домов превышен (если указан max_homes) 
    {
  "message": "Home limit exceeded. Maximum 5 homes allowed.",
  "code": "limit_exceeded",
  "details": {
    "player_uuid": "string",
    "current_count": 5,
    "max_homes": 5
  }
}

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/

Создает новую точку варпа с проверкой лимита per-player.

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

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

Параметры:

  • player_uuid (required) - UUID владельца варпа
  • name (required) - Глобально уникальное имя варпа
  • max_warps (optional) - Максимальное количество варпов для игрока

Статус: 201 Created

Ответ:

{
  "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": true,
  "description": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Ошибки:

  • 409 Conflict - Варп с таким именем уже существует 
    {
  "message": "Warp 'spawn' already exists",
  "code": "already_exists",
  "details": {
    "owner_uuid": "другой-uuid"
  }
}
  • 409 Conflict - Лимит варпов превышен (если указан max_warps) 
    {
  "message": "Warp limit exceeded. Maximum 10 warps allowed.",
  "code": "limit_exceeded",
  "details": {
    "player_uuid": "string",
    "current_count": 10,
    "max_warps": 10
  }
}

PATCH /warps/

Обновляет существующую точку варпа. Только владелец может редактировать варп.

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

{
  "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,
  "description": "string"
}

Параметры:

  • player_uuid (required) - UUID игрока (для проверки ownership)
  • name (required) - Имя варпа для обновления
  • Все остальные поля опциональны

Ответ:

{
  "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,
  "description": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Ошибки:

  • 403 Forbidden - Нет прав для редактирования варпа 
    {
  "message": "You don't have permission to update warp 'spawn'",
  "code": "permission_denied",
  "details": {
    "warp_owner": "uuid-владельца",
    "requested_by": "ваш-uuid"
  }
}
  • 404 Not Found - Варп не найден

DELETE /warps/

Удаляет точку варпа. Только владелец может удалить варп.

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

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

Параметры:

  • player_uuid (required) - UUID игрока (для проверки ownership)
  • name (required) - Имя варпа для удаления

Статус: 204 No Content

Ошибки:

  • 403 Forbidden - Нет прав для удаления варпа
  • 404 Not Found - Варп не найден

POST /warps/get

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

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

{
  "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": 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",
      "player_uuid": "string",
      "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 ключ
  • 403 Forbidden - недостаточно прав для выполнения операции (например, попытка удалить чужой варп)
  • 404 Not Found - ресурс не найден
  • 409 Conflict - конфликт ресурсов (ресурс уже существует, лимит превышен)
  • 500 Internal Server Error - внутренняя ошибка сервера

Тело ответа при ошибке имеет следующий формат:

{
  "message": "Human-readable error message",
  "code": "error_code",
  "details": {
    "additional": "context"
  }
}

Коды ошибок:

  • not_found - ресурс не найден (404)
  • already_exists - ресурс уже существует (409)
  • limit_exceeded - превышен лимит ресурсов (409)
  • permission_denied - нет прав на операцию (403)
  • invalid_state - некорректное состояние данных (400)
  • cooldown_active - кулдаун активен (400)