This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

MC Panel API - Полная документация

Версия: 1.0.0
Дата: 15 января 2026

📋 Содержание

Базовая информация
Быстрый старт
Аутентификация
Управление пользователями
Личный кабинет
Управление серверами
Управление файлами
Тикеты
OpenID Connect
Коды ошибок
Примеры интеграции
Postman коллекция

Базовая информация

Base URL: http://localhost:8000

Формат данных: JSON

Аутентификация: Bearer Token (JWT)

Все защищенные эндпоинты требуют заголовок:

Authorization: Bearer <token>

Заголовки запросов

Content-Type: application/json
Authorization: Bearer <token>

Формат ответов

{
  "message": "Success message",
  "data": {}
}

Быстрый старт

1. Регистрация

curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password123"}'

2. Вход

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password123"}'

Ответ:

{
  "access_token": "eyJhbGc...",
  "token_type": "bearer",
  "username": "admin",
  "role": "admin"
}

3. Использование токена

TOKEN="your_token_here"

curl http://localhost:8000/api/servers \
  -H "Authorization: Bearer $TOKEN"

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

POST /api/auth/register

Регистрация нового пользователя.

Body:

{
  "username": "string",
  "password": "string"
}

Response (200):

{
  "access_token": "string",
  "token_type": "bearer",
  "username": "string",
  "role": "admin|user"
}

POST /api/auth/login

Вход в систему.

Body:

{
  "username": "string",
  "password": "string"
}

Response (200):

{
  "access_token": "string",
  "token_type": "bearer",
  "username": "string",
  "role": "admin|user|support|banned"
}

Errors:

401 - Неверные учетные данные

GET /api/auth/me

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

Headers: Authorization: Bearer <token>

Response (200):

{
  "username": "string",
  "role": "admin|user|support|banned",
  "servers": ["server1", "server2"]
}

Управление пользователями

GET /api/users

Список всех пользователей.

PUT /api/users/{username}/role

Изменить роль пользователя (admin only). Body: {"role": "admin|user|support|banned"}

PUT /api/users/{username}/servers

Управление доступом к серверам. Body: {"servers": ["server1", "server2"]}

DELETE /api/users/{username}

Удалить пользователя (admin only).

Личный кабинет

GET /api/profile/stats

Статистика текущего пользователя.

GET /api/profile/stats/{username}

Статистика другого пользователя (admin/support).

PUT /api/profile/username

Изменить имя пользователя. Body: {"new_username": "string", "password": "string"}

PUT /api/profile/password

Изменить пароль. Body: {"old_password": "string", "new_password": "string"}

Управление серверами

GET /api/servers

Список серверов пользователя.

POST /api/servers/create

Создать новый сервер. Body:

{
  "name": "server1",
  "displayName": "My Server",
  "startCommand": "java -Xmx2G -jar server.jar nogui"
}

GET /api/servers/{server}/config

Получить конфигурацию сервера.

PUT /api/servers/{server}/config

Обновить конфигурацию сервера.

DELETE /api/servers/{server}

Удалить сервер (admin only).

POST /api/servers/{server}/start

Запустить сервер.

POST /api/servers/{server}/stop

Остановить сервер.

POST /api/servers/{server}/command

Отправить команду серверу. Body: {"command": "say Hello"}

GET /api/servers/{server}/stats

Получить статистику сервера (CPU, RAM, Disk).

WS /ws/servers/{server}/console

WebSocket для консоли сервера (логи в реальном времени).

Управление файлами

GET /api/servers/{server}/files?path={path}

Список файлов в директории.

POST /api/servers/{server}/files/create

Создать файл или папку. Body: {"type": "file|folder", "name": "string", "path": "string"}

POST /api/servers/{server}/files/upload?path={path}

Загрузить файл (multipart/form-data).

GET /api/servers/{server}/files/download?path={path}

Скачать файл.

GET /api/servers/{server}/files/content?path={path}

Получить содержимое текстового файла.

PUT /api/servers/{server}/files/content?path={path}

Сохранить содержимое файла. Body: {"content": "string"}

PUT /api/servers/{server}/files/rename?old_path={path}&new_name={name}

Переименовать файл.

POST /api/servers/{server}/files/move

Переместить файл. Body: {"source": "path", "destination": "path"}

DELETE /api/servers/{server}/files?path={path}

Удалить файл или папку.

Тикеты

GET /api/tickets

Список тикетов (свои или все для admin/support).

POST /api/tickets/create

Создать новый тикет. Body: {"title": "string", "description": "string"}

GET /api/tickets/{id}

Получить тикет по ID.

POST /api/tickets/{id}/message

Добавить сообщение в тикет. Body: {"text": "string"}

PUT /api/tickets/{id}/status

Изменить статус тикета (admin/support). Body: {"status": "pending|in_progress|closed"}

OpenID Connect

GET /api/auth/oidc/providers

Список доступных OIDC провайдеров.

GET /api/auth/oidc/{provider}/login

Начать аутентификацию через OIDC (redirect).

GET /api/auth/oidc/{provider}/callback

Callback от OIDC провайдера (redirect).

Коды ошибок

Код	Описание	Решение
200	Успешно	-
400	Неверный запрос	Проверьте формат данных
401	Не авторизован	Войдите в систему
403	Доступ запрещен	Недостаточно прав
404	Не найдено	Проверьте URL
500	Ошибка сервера	Обратитесь к администратору

Примеры интеграции

Python

import requests

class MCPanelAPI:
    def __init__(self, base_url, username, password):
        self.base_url = base_url
        self.token = None
        self.login(username, password)
    
    def login(self, username, password):
        r = requests.post(f"{self.base_url}/api/auth/login",
            json={"username": username, "password": password})
        self.token = r.json()["access_token"]
    
    def get_headers(self):
        return {"Authorization": f"Bearer {self.token}"}
    
    def get_servers(self):
        r = requests.get(f"{self.base_url}/api/servers",
            headers=self.get_headers())
        return r.json()
    
    def start_server(self, server_name):
        r = requests.post(
            f"{self.base_url}/api/servers/{server_name}/start",
            headers=self.get_headers())
        return r.json()

# Использование
api = MCPanelAPI("http://localhost:8000", "admin", "password")
servers = api.get_servers()
api.start_server("survival")

JavaScript

class MCPanelAPI {
  constructor(baseURL) {
    this.baseURL = baseURL;
    this.token = null;
  }

  async login(username, password) {
    const response = await fetch(`${this.baseURL}/api/auth/login`, {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify({username, password})
    });
    const data = await response.json();
    this.token = data.access_token;
  }

  getHeaders() {
    return {
      'Authorization': `Bearer ${this.token}`,
      'Content-Type': 'application/json'
    };
  }

  async getServers() {
    const response = await fetch(`${this.baseURL}/api/servers`, {
      headers: this.getHeaders()
    });
    return await response.json();
  }

  async startServer(serverName) {
    const response = await fetch(
      `${this.baseURL}/api/servers/${serverName}/start`,
      {method: 'POST', headers: this.getHeaders()}
    );
    return await response.json();
  }
}

// Использование
const api = new MCPanelAPI('http://localhost:8000');
await api.login('admin', 'password');
const servers = await api.getServers();
await api.startServer('survival');

cURL примеры

# Вход
TOKEN=$(curl -s -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"pass"}' \
  | jq -r '.access_token')

# Список серверов
curl http://localhost:8000/api/servers \
  -H "Authorization: Bearer $TOKEN"

# Создать сервер
curl -X POST http://localhost:8000/api/servers/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"survival","displayName":"Survival","startCommand":"java -jar server.jar"}'

# Запустить сервер
curl -X POST http://localhost:8000/api/servers/survival/start \
  -H "Authorization: Bearer $TOKEN"

# Отправить команду
curl -X POST http://localhost:8000/api/servers/survival/command \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"say Hello"}'

# Список файлов
curl "http://localhost:8000/api/servers/survival/files?path=plugins" \
  -H "Authorization: Bearer $TOKEN"

# Создать тикет
curl -X POST http://localhost:8000/api/tickets/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Problem","description":"Details"}'

Postman коллекция

Импорт коллекции

Откройте Postman
File → Import
Выберите файл MC_Panel_API.postman_collection.json
Коллекция готова к использованию

Настройка переменных

В коллекции настройте переменные:

baseUrl = http://localhost:8000
serverName = survival (или имя вашего сервера)
token = автоматически сохраняется после Login

Использование

Выполните запрос "Login" для получения токена
Токен автоматически сохранится в переменную token
Все остальные запросы будут использовать этот токен
Используйте любые эндпоинты из коллекции

Структура коллекции

Authentication - регистрация, вход, получение пользователя
Users - управление пользователями
Servers - управление серверами
Files - операции с файлами
Tickets - система тикетов
Profile - личный кабинет
OpenID Connect - OIDC провайдеры

Безопасность

JWT Токены

Срок действия: 7 дней
Алгоритм: HS256
Хранение: localStorage (фронтенд)

Лимиты и ограничения

Размер файла: не ограничен (зависит от сервера)
Количество запросов: не ограничено
Длина сообщения: не ограничена
Количество серверов: не ограничено
Срок хранения логов: 1000 последних строк

Changelog

1.0.0 (15.01.2026)

✨ Первый релиз API
✅ 37 эндпоинтов
✅ JWT аутентификация
✅ OpenID Connect
✅ WebSocket консоль
✅ Полное управление серверами
✅ Файловый менеджер
✅ Система тикетов

Поддержка

Документация проекта: ДОКУМЕНТАЦИЯ.md
Postman коллекция: MC_Panel_API.postman_collection.json
Тикеты: Используйте систему тикетов в панели

Версия API: 1.0.0
Дата обновления: 15 января 2026

Спасибо за использование MC Panel API! 🚀

MC Panel API - Полная документация

📋 Содержание

Базовая информация

Заголовки запросов

Формат ответов

Быстрый старт

1. Регистрация

2. Вход

3. Использование токена

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

POST /api/auth/register

POST /api/auth/login

GET /api/auth/me

Управление пользователями

GET /api/users

PUT /api/users/{username}/role

PUT /api/users/{username}/servers

DELETE /api/users/{username}

Личный кабинет

GET /api/profile/stats

GET /api/profile/stats/{username}

PUT /api/profile/username

PUT /api/profile/password

Управление серверами

GET /api/servers

POST /api/servers/create

GET /api/servers/{server}/config

PUT /api/servers/{server}/config

DELETE /api/servers/{server}

POST /api/servers/{server}/start

POST /api/servers/{server}/stop

POST /api/servers/{server}/command

GET /api/servers/{server}/stats

WS /ws/servers/{server}/console

Управление файлами

GET /api/servers/{server}/files?path={path}

POST /api/servers/{server}/files/create

POST /api/servers/{server}/files/upload?path={path}

GET /api/servers/{server}/files/download?path={path}

GET /api/servers/{server}/files/content?path={path}

PUT /api/servers/{server}/files/content?path={path}

PUT /api/servers/{server}/files/rename?old_path={path}&new_name={name}

POST /api/servers/{server}/files/move

DELETE /api/servers/{server}/files?path={path}

Тикеты

GET /api/tickets

POST /api/tickets/create

GET /api/tickets/{id}

POST /api/tickets/{id}/message

PUT /api/tickets/{id}/status

OpenID Connect

GET /api/auth/oidc/providers

GET /api/auth/oidc/{provider}/login

GET /api/auth/oidc/{provider}/callback

Коды ошибок

Примеры интеграции

Python

JavaScript

cURL примеры

Postman коллекция

Импорт коллекции

Настройка переменных

Использование

Структура коллекции

Безопасность

JWT Токены

Рекомендации

Лимиты и ограничения

Changelog

1.0.0 (15.01.2026)

Поддержка