📚 Обзор API

ServerCon API v3.2 предоставляет комплексный доступ к функциям мониторинга игровых серверов, аналитики и управления с улучшенной системой обработки ошибок и стандартизированными HTTP статус-кодами. Эта страница дает обзор всех доступных эндпоинтов и их возможностей.

🌐 Базовый URL

http://138.124.109.53:5000

🏷️ Версия API

Текущая версия: 3.2.0

🆕 Новые возможности v3.2

• Стандартизированные HTTP статус-коды для всех ответов API
• Улучшенная обработка ошибок с детальными кодами и подсказками
• Централизованная система ответов с единым форматом
• Расширенное тестирование с проверкой всех статус-кодов
• Встроенная документация статус-кодов в API

🆕 Новые возможности v3.1

• Система блокировки IP адресов с автоматической и ручной блокировкой
• Продвинутая валидация и безопасность входных данных
• Telegram Bot для администрирования через Telegram
• Новые профессиональные эндпоинты с расширенной функциональностью

🆕 Новые возможности v3.0

• Система подписок API с многоуровневыми лимитами
• Продвинутые лимиты почасовые, дневные и месячные
• Мониторинг использования с детальной аналитикой
• Автоматическое управление сроками действия подписок

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

Все ответы API представлены в стандартизированном формате JSON с единой структурой:

✅ Успешные ответы

{
  "success": true,
  "message": "Операция выполнена успешно",
  "data": { ... },
  "timestamp": 1640995200.0
}

❌ Ответы с ошибками

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Отсутствует или неверный API ключ",
    "status_code": 401,
    "details": {
      "hint": "Добавьте заголовок: Authorization: Bearer YOUR_API_KEY",
      "documentation": "/api/v1/docs"
    }
  },
  "timestamp": 1640995200.0
}

🎯 Основные возможности

🚀 Мониторинг в реальном времени

• 40+ типов игр - от Minecraft до Counter-Strike
• Мгновенные обновления статуса серверов
• Детальная статистика игроков и производительности
• Исторические данные для анализа трендов

📊 Аналитика и отчеты

• Глобальная статистика платформы
• Индивидуальная аналитика серверов
• Графики и диаграммы производительности
• Экспорт данных в различных форматах

⚙️ Управление и администрирование

• Принудительные проверки статуса серверов
• Управление промо-баллами и вайпами
• Мониторинг использования API
• Настройка уведомлений и алертов

📂 Категории Эндпоинтов

🔍 Эндпоинты Серверов

Мониторинг и запросы игровых серверов для более чем 40 поддерживаемых игр.

GET /api/v1/servers

Получить все серверы с дополнительной фильтрацией

// Получить все серверы
const servers = await fetch('http://138.124.109.53:5000/api/v1/servers', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

// Фильтр по игре
const mcServers = await fetch('http://138.124.109.53:5000/api/v1/servers?game_id=30', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

// Пагинация
const servers = await fetch('http://138.124.109.53:5000/api/v1/servers?page=1&limit=50', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

GET /api/v1/servers/{server_id}

Получить подробную информацию о конкретном сервере

const server = await api.get('/api/v1/servers/12345');

GET /api/v1/servers/by-ip/{ip_address}

Получить серверы по IP адресу или IP:порт

// Все серверы на IP
const servers = await api.get('/api/v1/servers/by-ip/192.168.1.1');

// Конкретный сервер по IP:порт
const server = await api.get('/api/v1/servers/by-ip/192.168.1.1:27015');

GET /api/v1/servers/game/{game_id}

Получить все серверы для конкретной игры

const minecraftServers = await api.get('/api/v1/servers/game/30');

GET /api/v1/servers/online

Получить только онлайн серверы

const onlineServers = await api.get('/api/v1/servers/online');

🎮 Эндпоинты Игр

Доступ к информации об играх и статистике.

GET /api/v1/games

Получить все поддерживаемые игры

const games = await api.get('/api/v1/games');

GET /api/v1/games/{game_id}/stats

Получить статистику для конкретной игры

// Статистика за последние 7 дней
const stats = await api.get('/api/v1/games/30/stats?days=7');

GET /api/v1/games/top/players

Получить топ игр по количеству игроков

const topGames = await api.get('/api/v1/games/top/players?limit=10');

POST /api/v1/games/{game_id}/view

Зарегистрировать просмотр игры

await api.post('/api/v1/games/30/view');

📊 Эндпоинты Аналитики

Доступ к подробной аналитике и историческим данным.

GET /api/v1/analytics/global

Получить глобальную статистику платформы

const globalStats = await api.get('/api/v1/analytics/global');

GET /api/v1/analytics/server/{server_id}

Получить аналитику для конкретного сервера

const serverAnalytics = await api.get('/api/v1/analytics/server/12345');

GET /api/v1/analytics/chart/{server_id}

Получить данные графика количества игроков

// Последние 24 часа
const chartData = await api.get('/api/v1/analytics/chart/12345?hours=24');

⚡ Эндпоинты Реального Времени

Получение статуса сервера в реальном времени и выполнение мгновенных проверок.

GET /api/v1/servers/check/{server_id}

Выполнить мгновенную проверку статуса сервера (только для администраторов)

const status = await api.get('/api/v1/servers/check/12345');

GET /api/v1/server/stats/{server_id}

Получить статистику сервера в реальном времени

const liveStats = await api.get('/api/v1/server/stats/12345');

⚙️ Общие Параметры

📚 Пагинация

Большинство эндпоинтов списков поддерживают пагинацию:

• page: Номер страницы (по умолчанию: 1)
• limit: Количество элементов на страницу (по умолчанию: 50, максимум: 100)

const servers = await api.get('/api/v1/servers?page=2&limit=25');

⏰ Временные Фильтры

Многие эндпоинты поддерживают фильтрацию по времени:

• days: Количество дней назад (по умолчанию: 7)
• hours: Количество часов назад
• from: Дата начала (формат ISO)
• to: Дата окончания (формат ISO)

// Последние 30 дней
const stats = await api.get('/api/v1/games/stats?days=30');

// Определенный диапазон дат
const stats = await api.get('/api/v1/games/stats?from=2024-01-01&to=2024-01-31');

🔄 Сортировка

Сортировка результатов с помощью параметра sort:

• sort=players: Сортировка по количеству игроков
• sort=name: Алфавитная сортировка
• sort=created_at: Сортировка по дате создания
• Добавьте префикс - для убывающего порядка

// Самые популярные серверы в начале
const servers = await api.get('/api/v1/servers?sort=-players');

📄 Примеры Ответов

💻 Ответ Сервера

{
  "success": true,
  "data": {
    "id": 12345,
    "name": "Мой Minecraft Сервер",
    "game_id": 30,
    "game_name": "Minecraft",
    "ip": "192.168.1.1",
    "port": 25565,
    "players": {
      "online": 45,
      "max": 100
    },
    "status": "online",
    "version": "1.20.4",
    "map": "world",
    "country": "US",
    "last_seen": "2024-01-15T10:30:00Z",
    "uptime_percentage": 98.5
  }
}

🎮 Ответ Статистики Игр

{
  "success": true,
  "data": {
    "game_id": 30,
    "game_name": "Minecraft",
    "period": {
      "days": 7,
      "from": "2024-01-08T00:00:00Z",
      "to": "2024-01-15T00:00:00Z"
    },
    "statistics": {
      "peak_players": 15420,
      "avg_players": 8930,
      "min_players": 2100,
      "total_servers": 1245,
      "active_servers": 1180,
      "views": 8500,
      "clicks": 2100
    },
    "daily_breakdown": [
      {
        "date": "2024-01-15",
        "peak_players": 2200,
        "avg_players": 1800,
        "active_servers": 185
      }
    ]
  }
}

📊 HTTP Статус-коды

✅ Успешные ответы

Код	Название	Описание	Примеры
200	OK	Запрос выполнен успешно	Получение списка серверов
201	Created	Ресурс создан успешно	Создание API ключа
202	Accepted	Запрос принят к обработке	Асинхронные операции

❌ Ответы с ошибками

Код	Название	Описание	Код ошибки API
400	Bad Request	Некорректный запрос	VALIDATION_FAILED
401	Unauthorized	Неверный API ключ	UNAUTHORIZED
403	Forbidden	Недостаточно прав	INSUFFICIENT_PERMISSIONS
404	Not Found	Ресурс не найден	RESOURCE_NOT_FOUND
422	Unprocessable Entity	Ошибка валидации	VALIDATION_FAILED
429	Too Many Requests	Превышен лимит	RATE_LIMIT_EXCEEDED
500	Internal Server Error	Внутренняя ошибка	DATABASE_ERROR

🔍 Примеры ошибок

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Отсутствует или неверный API ключ",
    "status_code": 401,
    "details": {
      "hint": "Добавьте заголовок: Authorization: Bearer YOUR_API_KEY",
      "documentation": "/api/v1/docs"
    }
  },
  "timestamp": 1640995200.0
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Недостаточно прав для операции",
    "status_code": 403,
    "details": {
      "hint": "Обновите тип API ключа или обратитесь к администратору",
      "documentation": "/api/v1/docs"
    }
  },
  "timestamp": 1640995200.0
}

429 Too Many Requests

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Превышен лимит запросов. Дождитесь сброса лимита",
    "status_code": 429,
    "details": {
      "hint": "Дождитесь сброса лимита или обновите подписку",
      "retry_after": "3600",
      "documentation": "/api/v1/docs"
    }
  },
  "timestamp": 1640995200.0
}

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

1️⃣ Получите API ключ

Используйте тестовый ключ test_key_12345 или получите свой в личном кабинете.

2️⃣ Сделайте первый запрос

curl -H "Authorization: Bearer test_key_12345" \
     http://138.124.109.53:5000/api/v1/servers?limit=5

3️⃣ Изучите ответ

{
  "success": true,
  "message": "Операция выполнена успешно",
  "data": [
    {
      "id": 12345,
      "name": "Мой сервер",
      "game_id": 30,
      "game_name": "Minecraft",
      "players": {
        "online": 45,
        "max": 100
      },
      "status": "online"
    }
  ],
  "timestamp": 1640995200.0
}

4️⃣ Тестирование ошибок

# Быстрый тест основных ошибок
python quick_error_test.py

# Полное тестирование с новыми категориями
python test_api.py --errors

# Интерактивный режим с тестами ошибок
python test_api.py --interactive

🎯 Популярные сценарии использования

📱 Мобильные приложения

// Получить топ серверов для мобильного приложения
const topServers = await api.get('/api/v1/servers?sort=-players&limit=20');

// Получить статистику для дашборда
const stats = await api.get('/api/v1/analytics/global');

🌐 Веб-сайты

// Встроить список серверов на сайт
const servers = await api.get('/api/v1/servers/game/30?limit=10');

// Показать статистику игры
const gameStats = await api.get('/api/v1/games/30/stats?days=30');

🤖 Боты Discord/Telegram

// Проверить статус сервера для бота
const server = await api.get('/api/v1/servers/12345');

// Получить топ игр для команды
const topGames = await api.get('/api/v1/games/top/players?limit=5');

📊 Аналитические панели

// Создать дашборд с аналитикой
const globalStats = await api.get('/api/v1/analytics/global');
const serverAnalytics = await api.get('/api/v1/analytics/server/12345');
const chartData = await api.get('/api/v1/analytics/chart/12345?hours=24');

🔧 Интеграция с популярными платформами

🟨 React/Next.js

import { useState, useEffect } from 'react';

function ServerList() {
  const [servers, setServers] = useState([]);
  
  useEffect(() => {
    fetch('/api/v1/servers?limit=10', {
      headers: { 'Authorization': 'Bearer test_key_12345' }
    })
    .then(res => res.json())
    .then(data => setServers(data.data));
  }, []);
  
  return (
    <div>
      {servers.map(server => (
        <div key={server.id}>
          <h3>{server.name}</h3>
          <p>{server.players.online}/{server.players.max} игроков</p>
        </div>
      ))}
    </div>
  );
}

🐍 Django/Flask

import requests

def get_server_stats(server_id):
    response = requests.get(
        f'http://138.124.109.53:5000/api/v1/servers/{server_id}',
        headers={'Authorization': 'Bearer test_key_12345'}
    )
    return response.json()

💻 WordPress

function get_servercon_servers($game_id = 30) {
    $response = wp_remote_get(
        "http://138.124.109.53:5000/api/v1/servers/game/{$game_id}",
        array(
            'headers' => array(
                'Authorization' => 'Bearer test_key_12345'
            )
        )
    );
    
    return json_decode(wp_remote_retrieve_body($response), true);
}

📈 Производительность и оптимизация

⚡ Рекомендации по производительности

1. Используйте пагинацию для больших списков
2. Кэшируйте результаты на стороне клиента
3. Используйте фильтры для уменьшения объема данных
4. Обрабатывайте ошибки gracefully

🔄 Кэширование

// Простой кэш на стороне клиента
const cache = new Map();

async function getCachedServers(gameId) {
  const cacheKey = `servers_${gameId}`;
  
  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }
  
  const data = await api.get(`/api/v1/servers/game/${gameId}`);
  cache.set(cacheKey, data);
  
  // Очистить кэш через 5 минут
  setTimeout(() => cache.delete(cacheKey), 5 * 60 * 1000);
  
  return data;
}

🔜 Следующие Шаги

• Изучите эндпоинты серверов подробно
• Узнайте о статистике игр
• Посмотрите практические примеры

📚 Дополнительные ресурсы

• 🔐 Аутентификация
• 💡 Примеры использования
• ❓ Часто задаваемые вопросы

🆘 Поддержка

Если у вас возникли вопросы по API:

1. Проверьте документацию по конкретному эндпоинту
2. Используйте тестовый ключ для экспериментов
3. Обратитесь в поддержку через личный кабинет
4. Присоединяйтесь к сообществу разработчиков

Совет

Начните с простых запросов и постепенно переходите к более сложным интеграциям!