API для розробників та власників серверів

Що таке API і навіщо воно вам?

Простими словами, API — це ваш особистий міст між даними нашого моніторингу та вашими власними проєктами. Замість того, щоб вручну копіювати інформацію, ви можете автоматизувати цей процес.

З нашим API ви можете:

Створити Discord-бота, що показує онлайн та ранг вашого сервера.
Додати динамічний віджет на ваш сайт, що автоматично оновлюється.
Аналізувати статистику голосів та активності для розвитку проєкту.
Розробити власний мобільний додаток для вашої спільноти.

Аутентифікація та типи методів

Наш API має два типи методів:

  • Публічні методи: Не потребують API-ключа. Надають загальнодоступну інформацію (статус сервера, топ рейтингу).
  • Приватні методи: Потребують API-ключа. Надають вашу особисту статистику.

Щоб отримати ключ, перейдіть у налаштування вашого профілю та згенеруйте його. Нікому не передавайте цей ключ!

Передавайте ключ у заголовку запиту (рекомендований спосіб):

Authorization: Bearer ВАШ_API_КЛЮЧ

Приклади використання

Публічний запит (отримання даних сервера ID 123):

<?php
$ch = curl_init("https://mcua.top/api/v1/server/123");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
print_r($data);
?>

Приватний запит (отримання вашої статистики):

<?php
$apiKey = "ВАШ_API_КЛЮЧ";
$ch = curl_init("https://mcua.top/api/v1/my-stats");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . $apiKey
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
print_r($data);
?>

Публічний запит (отримання даних сервера ID 123):

import requests

response = requests.get("https://mcua.top/api/v1/server/123")
data = response.json()
print(data)

Приватний запит (отримання вашої статистики):

import requests

api_key = "ВАШ_API_КЛЮЧ"
headers = {
    "Authorization": f"Bearer {api_key}"
}
response = requests.get("https://mcua.top/api/v1/my-stats", headers=headers)
data = response.json()
print(data)

Публічний запит (отримання даних сервера ID 123):

fetch("https://mcua.top/api/v1/server/123")
    .then(response => response.json())
    .then(data => console.log(data));

Приватний запит (отримання вашої статистики):

const apiKey = "ВАШ_API_КЛЮЧ";

fetch("https://mcua.top/api/v1/my-stats", {
    headers: {
        "Authorization": `Bearer ${apiKey}`
    }
})
.then(response => response.json())
.then(data => console.log(data));

Публічний запит (отримання даних сервера ID 123):

curl "https://mcua.top/api/v1/server/123"

Порада: для гарного форматування JSON-відповіді в терміналі встановіть утиліту `jq` і додайте в кінець команди `| jq`.

Публічний запит з параметрами (топ 3 Bedrock серверів):

curl "https://mcua.top/api/v1/top?limit=3&type=bedrock"

Важливо: завжди беріть URL з параметрами в лапки, щоб уникнути конфліктів з символами терміналу (наприклад, `&`).

Приватний запит (отримання вашої статистики):

curl -H "Authorization: Bearer ВАШ_API_КЛЮЧ" "https://mcua.top/api/v1/my-stats"

Замініть `ВАШ_API_КЛЮЧ` на ваш реальний ключ з налаштувань профілю.

Доступні методи (Endpoints)

GET /api/v1/server/{id}
Отримати публічну інформацію про конкретний сервер. Публічний

Приклад відповіді:

{
    "success": true,
    "server": {
        "id": 123,
        "name": "Мій Крутий Сервер",
        "address": "play.example.com:25565",
        "is_online": true,
        "players": { "online": 57, "max": 100 },
        "version": "1.20.1",
        "types": ["Виживання", "PvP"],
        "platform": "java",
        "rank": 5,
        "votes": 1234,
        "uptime": 99.8
    }
}

GET /api/v1/top
Отримати список топ серверів. Публічний

Параметри запиту: limit (макс. 50, за замовчуванням 10), type ('java' або 'bedrock', за замовчуванням 'java').

Приклад запиту: https://mcua.top/api/v1/top?limit=3&type=bedrock

GET /api/v1/my-stats
Отримати розширену інформацію та статистику для всіх ваших серверів. Потрібен API-ключ

Приклад відповіді:

{
    "success": true,
    "my_servers": [
        {
            "id": 123,
            "name": "Мій Крутий Сервер",
            "address": "play.example.com:25565",
            "is_online": true,
            "players": {
                "online": 57,
                "max": 100
            },
            "version": "1.20.1",
            "rank": 5,
            "stats": {
                "votes_month": 1234,
                "votes_all_time": 8567,
                "views": 2500,
                "ip_copies": 800,
                "comments": 45,
                "favorites": 120,
                "uptime_percent": 99.8
            }
        }
    ]
}

Обробка помилок

API використовує стандартні HTTP-коди для повідомлення про результат запиту: 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found.

140
Серверів
109
Java
31
Bedrock
344
Гравці
33
Реєстрації
1 / 2
Активність