ГоловнаБлогЗовнішній API Монікор: повний гайд з підключення даних сервера на сайт

Зовнішній API Монікор: повний гайд з підключення даних сервера на сайт

Покрокова інструкція з прикладами коду на Python та JavaScript, описом усіх полів і відповідями на типові запитання

Автор: Монікор

Якщо ви ведете ігровий сервер у моніторингу Монікор, у певний момент стає очевидним: статистика з кабінету варта того, щоб опинитися не лише на платформі, а й на головній сторінці вашого сайту, у Discord-боті спільноти, на лаунчері клієнта, у щоденному звіті адмін-каналу. Гравці бачать живі цифри і відчувають, що проєкт розвивається. Адмін отримує дані для рішень. Маркетолог бачить ефект кампаній.

Перша думка - просто парсити сторінку Монікор. Це погана ідея з кількох причин: дизайн оновлюється, дані тягнуться через JavaScript, а політика платформи прямо забороняє автоматичний скрейпінг. Правильний інструмент - офіційний Зовнішній API, який повертає всі публічні дані у структурованому JSON.

Що таке Зовнішній API Монікор

Зовнішній API - це REST-ендпоінт, який повертає публічну інформацію про ваш сервер у форматі JSON. На відміну від внутрішніх API платформи, Зовнішній API розроблений саме для того, щоб ви виводили дані поза межі Монікор: на вашому сайті, у боті, в аналітичній системі, у CRM спільноти.

За базовим запитом ви отримуєте основні поля: id сервера, slug (URL-сегмент), назва, середній рейтинг, дата реєстрації. Якщо потрібно більше, додаєте параметри і отримуєте розширену відповідь зі списками голосів, лайків та коментарів від реальних гравців.

Чому API краще за парсинг сторінки

  • Стабільність: API не залежить від HTML-розмітки. Ми можемо переробити дизайн сайту, але ваш скрипт продовжить працювати без змін.
  • Швидкість: JSON-відповідь у середньому 2-5 КБ проти кількох сотень КБ HTML-сторінки з картинками і скриптами.
  • Точність: жодних регулярних виразів, що ловлять зайві символи. Кожне поле має чіткий тип і назву.
  • Дозвіл: парсинг порушує правила платформи, API навпаки створений саме для інтеграції.
  • Авторизація: лише ви, як власник сервера, маєте доступ до своїх даних через персональний ключ.

Як отримати API-ключ за 30 секунд

Доступ закритий ключем, щоб ніхто, крім вас, не міг безконтрольно отримувати ваші дані. Процес простий.

Зайдіть в особистий кабінет Монікор і відкрийте налаштування свого сервера. Знайдіть розділ "API" або "Інтеграції". Натисніть кнопку згенерувати ключ. Він з'явиться як довгий рядок випадкових символів, який копіюється в один клік.

Зберігайте ключ у безпечному місці: змінних середовища (.env), менеджері секретів вашого хостингу, секретах GitHub Actions. Не публікуйте його у відкритому коді на GitHub чи в публічних чатах. Якщо ключ скомпрометовано, ви завжди можете перевипустити його одним натисканням, і старий одразу перестане працювати.

Структура запиту

Базовий запит мінімалістичний. Метод GET, URL ендпоінта /api/external/server/, заголовок із ключем:

GET /api/external/server/
X-Monicore-API-Key: ваш_api_ключ

Ключ передається саме у заголовку, а не у параметрах URL. Це безпечніше: заголовки не потрапляють у логи проксі та не зберігаються в історії браузера.

Розширені параметри запиту

Базова відповідь компактна. Якщо потрібні додаткові дані, ви явно запитуєте їх через query-параметри:

  • votes_today - список голосів за сьогодні з нікнеймами і timestamp
  • votes_month - голоси за поточний місяць
  • votes_prev_month - голоси за попередній місяць (зручно для звітів)
  • votes_all - усі голоси за весь час існування сервера
  • likes - список тих, хто поставив лайк
  • comments - коментарі без відповідей

Параметри комбінуються: ?votes_today=true&likes=true поверне і голоси за сьогодні, і список лайків в одній відповіді. Це економить запити і допомагає вкладатися в ліміти.

Структура відповіді JSON

Кожне поле має чіткий тип, який легко обробити у будь-якій мові програмування:

  • id (number) - числовий ідентифікатор сервера в системі
  • slug (string) - URL-friendly назва, та сама, що в адресі сторінки
  • name (string) - повна назва сервера, як ви її вказали
  • rating (float) - середній рейтинг від 0 до 5 з десятковою частиною
  • created_at (datetime) - дата реєстрації у форматі ISO 8601
  • votes_*, likes, comments (array, опційно) - масиви об'єктів з полями user_id, user_nickname, created_at

Приклад реальної відповіді сервера з рейтингом 4.8 та одним голосом сьогодні:

{
  "id": 42,
  "slug": "my-server",
  "name": "My Server",
  "rating": 4.8,
  "created_at": "2024-01-15T10:30:00Z",
  "votes_today": [
    {
      "user_id": "123456789",
      "user_nickname": "PlayerName",
      "created_at": "2025-03-18T09:00:00Z"
    }
  ]
}

Приклад інтеграції на Python

Якщо хочете оновлювати віджет на сайті раз на хвилину, скрипт виглядатиме приблизно так:

import requests

API_KEY = "your_api_key_here"
URL = "https://monicore.com.ua/api/external/server/"

headers = {"X-Monicore-API-Key": API_KEY}
params = {"votes_today": True, "likes": True}

response = requests.get(URL, headers=headers, params=params)
data = response.json()

print(f"Рейтинг: {data['rating']}")
print(f"Голосів сьогодні: {len(data['votes_today'])}")
print(f"Лайків загалом: {len(data['likes'])}")

На JavaScript для Discord-бота на discord.js принцип той самий: робите fetch, передаєте заголовок, парсите JSON, відправляєте в канал як Embed.

Сім реальних сценаріїв використання

  • Віджет на головній сторінці сайту - великим шрифтом середній рейтинг, поруч кількість голосів за сьогодні. Гравець бачить, що сервер живий.
  • Топ голосуючих місяця - збираєте votes_month, рахуєте кожного user_id, виводите перших 10. Видаєте їм бонуси у грі.
  • Discord-бот зі статистикою - команда /stats виводить Embed з поточним рейтингом і кількістю активних голосів.
  • Daily report у Discord - о 09:00 щодня бот публікує в адмін-каналі звіт за вчора: голоси, лайки, нові коментарі.
  • Лідерборд лайків - окрема сторінка-вітрина найактивніших фанатів сервера.
  • Інтеграція з лаунчером - при запуску клієнта показуєте поточний рейтинг і онлайн.
  • Аналітика у Google Sheets - щогодинний скрипт пише дані у таблицю, ви будуєте графіки росту.

Ліміти та обробка помилок

На API діє обмеження - 20 запитів за хвилину з одного ключа. Цього вистачає для будь-яких реальних задач: оновлення віджета раз на 3 секунди, регулярний експорт у базу, періодичні звіти. Якщо ваш скрипт раптом перевищує цей ліміт, варто переглянути архітектуру - швидше за все, є зайві запити.

Помилки повертаються стандартними HTTP-кодами:

  • 403 Forbidden - API-ключ відсутній або невірний. Перевірте, чи правильно скопіювали ключ і чи передаєте його у заголовку.
  • 404 Not Found - сервер не знайдено або тимчасово недоступний. Можливо, його видалили з моніторингу або приховали.
  • 429 Too Many Requests - перевищено ліміт. Зачекайте хвилину і спробуйте знову.
  • 500 Server Error - внутрішня помилка з нашого боку. Якщо повторюється, напишіть у підтримку.

Живий тестер у браузері

На сторінці інструмента є секція "Тест API". Вставляєте свій ключ, ставите галочки на потрібні параметри, натискаєте кнопку і одразу бачите реальну відповідь у красиво відформатованому JSON. Це найшвидший спосіб переконатися, що ключ працює, побачити структуру відповіді на конкретному прикладі та зрозуміти, які саме поля прийдуть до вашого скрипта.

Поширені запитання

Чи треба платити за API-ключ? Ні, доступ безкоштовний для всіх власників серверів на Монікор.

Скільки ключів можна створити? На один сервер видається один ключ. Цього достатньо для будь-яких сценаріїв, бо ключ нічим не обмежений у використанні.

Що робити, якщо ключ скомпрометовано? Перевипустіть його в особистому кабінеті. Старий одразу перестане працювати, новий заробить за лічені секунди.

Чи можна викликати API з браузера через JavaScript на сайті? Технічно можна, але робити цього не варто: ключ буде видно в DevTools будь-якому відвідувачу. Краще проксіювати запити через ваш бекенд або кешувати дані на сервері.

Як часто оновлюються дані? Дані в API живі - кожен запит повертає актуальний стан без кешу.

Підсумок

Зовнішній API Монікор - це міст між нашим моніторингом і вашою інфраструктурою. Один захищений ендпоінт, гнучкий набір параметрів, чесні JSON-дані без сюрпризів. Якщо хочете показувати рейтинг, голоси та активність гравців у власному просторі, починати треба саме з нього.

Назад до блогу