REST HTTP API
Представьте, что ваш сервер Minecraft умеет общаться с внешним миром не только через игровой чат, но и по протоколу HTTP. Именно это и делает плагин REST HTTP API — он превращает ядро Paper в полноценный веб-сервис, готовый принимать команды и отдавать данные по любому REST-запросу. Больше не нужно заходить в консоль или писать сложные обёртки: достаточно отправить HTTP-вызов, и сервер выполнит нужное действие, будь то выдача предмета, смена погоды или получение списка онлайна.
Что умеет REST HTTP API
Плагин создавался с прицелом на максимальную гибкость, поэтому набор возможностей впечатляет. Вот ключевые функции, которые вы получаете сразу после установки:
- Выполнение любых серверных команд Minecraft через HTTP-запросы — от бана игрока до настройки мира.
- RESTful эндпоинты для получения информации о сервере: TPS, количество игроков, версия и многое другое.
- Аутентификация по Bearer-токену, чтобы доступ к API имели только доверенные приложения.
- Очередь команд для офлайн-игроков: если цель не в сети, команда не потеряется и выполнится при следующем входе.
- Режим ожидания входа игрока перед выполнением команды — идеально для сценариев, где нужно дождаться конкретного участника.
- Автоматически генерируемая интерактивная документация API в формате Swagger UI, которая всегда актуальна.
Требования и совместимость с версиями Minecraft
REST HTTP API ориентирован на серверное ядро Paper и его форки. Хотя Spigot и Bukkit могут запустить плагин, официально они не тестировались, поэтому для стабильной работы настоятельно рекомендуется использовать именно Paper. Обязательное условие — Java 17 или новее. Что касается версий Minecraft, плагин без проблем работает с актуальными сборками 1.20.x и 1.21.x, а также с более старыми релизами, где поддерживается Paper. Это делает REST HTTP API для Minecraft универсальным инструментом, который не придётся менять при обновлении сервера.
Как установить REST HTTP API
Самый простой способ получить плагин — скачать REST HTTP API с официальной страницы релизов. Найдите файл с именем http-commands-*.jar последней версии и переместите его в папку plugins вашего сервера. После перезапуска или выполнения команды reload плагин автоматически создаст конфигурационный файл и запустит встроенный HTTP-сервер. Если вы предпочитаете собирать из исходников, клонируйте репозиторий и выполните ./gradlew build — готовый JAR появится в build/libs.
Впрочем, ручная установка — не единственный путь. Пользователи лаунчера foxygame.net могут добавить REST HTTP API через встроенный каталог дополнений: плагин устанавливается в один клик, а все обновления приходят автоматически, что избавляет от необходимости следить за новыми версиями вручную.
Настройка и безопасность
После первого запуска плагин создаёт файл plugins/http-commands/config.yml. Первым делом откройте его и замените Bearer-токен на длинную случайную строку — это ваш главный ключ доступа ко всему API. Никогда не используйте токен по умолчанию на публичных серверах. Для дополнительной защиты обязательно настройте обратный прокси с HTTPS (Nginx или Caddy) и ограничьте входящие подключения файрволом только доверенными IP-адресами. Так вы исключите риск перехвата токена и несанкционированных команд.
Пример настройки Nginx
Приведённый ниже конфиг оборачивает API в защищённое соединение и проксирует запросы к локальному порту плагина:
server {
listen 443 ssl;
server_name mc-api.example.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}Документация API и тестирование
Одна из сильных сторон REST HTTP API — автоматически генерируемая документация. Она строится на основе спецификации OpenAPI и доступна в виде интерактивного Swagger UI. Вы можете открыть её в браузере, изучить все эндпоинты, посмотреть схемы запросов и ответов, а главное — сразу протестировать вызовы, не покидая интерфейс. Это колоссально ускоряет разработку внешних интеграций: веб-панелей, ботов для Discord или скриптов автоматизации. Документация всегда соответствует текущей версии плагина, поэтому вам не придётся гадать, какие параметры принимает тот или иной метод.
Управление плагином
Единственная игровая команда, которую добавляет REST HTTP API — /http-commands reload. Она перезагружает конфигурацию и перезапускает HTTP-сервер, что бывает полезно после смены токена или порта. Для выполнения команды требуется право httpcommands.reload, поэтому выдавайте его только администраторам. Никаких других команд не предусмотрено, и это логично: всё управление происходит через само API.
Почему стоит выбрать REST HTTP API
Плагин распространяется под лицензией MIT, а значит, вы можете свободно использовать, модифицировать и даже встраивать его в коммерческие проекты. Лёгковесный, не требовательный к ресурсам и предельно прозрачный — он идеально вписывается в экосистему современного сервера Minecraft. Если вы когда-либо задумывались о том, чтобы связать игровой мир с веб-приложением, настроить автоматическую выдачу наград через сайт или построить админ-панель с кнопками вместо консольных команд, REST HTTP API станет тем самым недостающим звеном. Просто скачайте REST HTTP API, настройте токен и откройте для себя совершенно новый уровень управления сервером.