API MineList дозволяє твоєму серверу перевірити, чи проголосував гравець, видати нагороду рівно один раз і зчитати публічну статистику. Усі ендпойнти повертають JSON і працюють на звичайних запитах HTTPS GET, тож підходять для будь-якої мови програмування.
Як отримати API-ключ
Додай свій сервер, підтверди його та відкрий панель власника. API-ключ показано на сторінці налаштувань сервера. Тримай його в таємниці, адже він ідентифікує твій сервер. Якщо ключ витече, згенеруй у панелі новий і онови плагін або скрипт.
Базова адреса всіх ендпойнтів – https://minelist.eu.
Перевірка голосу
GET /api/v1/vote?key=API_KEY&username=NICKПоказує, чи проголосував гравець сьогодні та чи нагороду вже отримано.
{"voted":true,"claimed":false,"next_vote_utc":"2026-10-31T00:00:00Z"}votedмає значення true, якщо для твого сервера є голос цього ніка в поточну добу за UTC.claimedмає значення true, якщо цей голос уже позначено як отриманий.next_vote_utc– час, коли гравець зможе проголосувати знову.
Позначення голосу як отриманого
GET /api/v1/vote/claim?key=API_KEY&username=NICKПозначає сьогоднішній голос як отриманий. Викликай цей запит безпосередньо перед видачею нагороди, щоб гравець не зміг отримати її двічі. Можливі відповіді:
| Відповідь | Значення |
|---|---|
{"voted":true,"claimed":true} | Голос був дійсним і тепер позначений як отриманий. Видай нагороду. |
{"voted":true,"claimed":false,"already_claimed":true} | Голос уже було отримано раніше. Нічого не видавай. |
{"voted":false,"claimed":false} | Гравець сьогодні не голосував. |
Список голосів цього місяця
GET /api/v1/votes?key=API_KEYПовертає всі голоси, які твій сервер отримав у поточному місяці. Це корисно для щомісячних нагород найактивнішим гравцям і для таблиць лідерів на твоєму сайті.
Публічна статистика сервера
GET /api/v1/server/<slug>Цей ендпойнт не потребує ключа. Slug – це остання частина адреси сервера на MineList. Приклад полів відповіді:
| Поле | Опис |
|---|---|
name | Назва сервера |
url | Сайт сервера |
ip | Адреса підключення |
online | Чи була остання перевірка успішною |
players | Гравців онлайн під час останньої перевірки |
max_players | Кількість слотів для гравців |
version | Версія сервера |
votes_month | Голоси цього місяця |
votes_total | Голоси від моменту додавання сервера |
uptime_30 | Аптайм за останні 30 днів у відсотках |
rating | Середня оцінка |
last_check | Час останньої перевірки |
Приклад із curl
Ось уся логіка в командному рядку. Те саме зробить будь-яка мова, що вміє надсилати HTTP-запити, наприклад Java, PHP, Python чи Node.js.
curl -s "https://minelist.eu/api/v1/vote/claim?key=API_KEY&username=Steve"Розбери JSON, і якщо claimed має значення true, виконай команду видачі нагороди, наприклад give Steve diamond 3.
Підтримка NuVotifier
Якщо хочеш отримувати нагороди миттєво, без опитування, MineList може надсилати голоси на твій сервер через NuVotifier. Підтримуються обидві версії протоколу. Версія 1 використовує публічний ключ RSA, версія 2 – токен.
- Встанови NuVotifier на сервері й перезапусти його.
- У панелі власника введи хост, порт (за замовчуванням 8192) і публічний ключ (v1) або токен (v2).
- Натисни Надіслати тестовий голос і переконайся, що сервер записав голос у лог.
Якщо тест не вдався, переконайся, що порт Votifier відкрито у твоєму файрволі та що ключ скопійовано без пробілів і переносів рядків.
Живий банер
Кожен сервер має живий банер розміром 468x60 пікселів, який показує поточний статус і кількість гравців:
https://minelist.eu/banner/<slug>.pngПриклад вбудовування в HTML:
<a href="https://minelist.eu/uk/server/vash-slug">
<img src="https://minelist.eu/banner/vash-slug.png" width="468" height="60" alt="Голосуй за нас на MineList">
</a>Практичні поради
- Кешуй публічну статистику щонайменше на хвилину, замість того щоб викликати API при кожному перегляді сторінки.
- Ніколи не розміщуй API-ключ у клієнтському коді чи публічному репозиторії.
- Використовуй ендпойнт claim лише один раз для кожної нагороди.