Содержание

Обзор Политика версионирования Обратная совместимость Миграция с V1 на V2 Изменения в эндпоинтах Обновления формата ответа График устаревания Критические изменения Пошаговая миграция Поддержка и ресурсы

Документация API

Руководство по миграции API — Обновление между версиями

Планируйте и выполняйте плавное обновление версий API. Узнайте о критических изменениях, графиках устаревания и лучших практиках миграции между версиями Smart Money API.

Опубликовано 21 марта 2026 • 16 мин. чтения • Продвинутый уровень

Обзор миграции

Smart Money API активно развивается с регулярными обновлениями. Это руководство охватывает управление версиями, критические изменения и способы миграции вашей интеграции без простоев.

Ключевые принципы миграции:

Семантическое версионирование — Строго соблюдается формат MAJOR.MINOR.PATCH
Долгосрочная поддержка — Предыдущая мажорная версия поддерживается 24+ месяца
Предупреждения об устаревании — Уведомление за 6 месяцев о всех критических изменениях
Параллельные версии — Одновременная работа v1 и v2 во время миграции
Автоматизированное тестирование — Предоставляются инструменты для проверки совместимости

Текущий статус: v1 (текущая), v2 (бета, общедоступная версия Q2 2026). v1 поддерживается до Q1 2028.

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

Семантическое версионирование

Формат версии
Версия API: MAJOR.MINOR.PATCH
Пример: 2.1.3
MAJOR (2) — Критические изменения, новая архитектура
MINOR (1) — Совместимые с предыдущими версиями функции
PATCH (3) — Исправления ошибок, обновления безопасности

Цикл выпуска версий

Фаза	Длительность	Характеристики
Альфа	2-4 недели	Частые критические изменения, только тестирование
Бета	4-8 недель	В основном стабильна, сбор отзывов сообщества
Результат-кандидат	2-4 недели	Готова к продакшену, финальная доработка
Общедоступная версия	24+ месяца	Полная поддержка продакшена

Получите ваш API-ключ за 30 секунд

Готовы к разработке? Получите бесплатный API-ключ (100 вызовов/день, без карты) и начните получать данные о китах, фандинге и ончейн-данных в реальном времени.

Получить API-ключ →

Обратная совместимость

Совместимость версий

В рамках мажорной версии вы всегда можете безопасно обновляться до новых минорных/патч-версий:

URL эндпоинтов — Остаются неизменными
Обязательные поля — Никогда не удаляются (добавляются только новые необязательные поля)
HTTP-коды статусов — Сохраняются для существующих сценариев
Структура ответа — Основные поля остаются идентичными
Аутентификация — Нет изменений в механизмах аутентификации

Плавное устаревание

График устаревания
// Месяц 1: Объявление об устаревании
// Функция помечена заголовком Deprecation
Deprecation: version="2.2", sunset="2026-09-01"
// Месяц 3-6: Активный период устаревания
// API возвращает предупреждения, но продолжает работать
X-Deprecation-Warning: Этот эндпоинт будет удален 2026-09-01
// Месяц 6: Окончательное удаление
// Эндпоинт возвращает 410 Gone
HTTP/1.1 410 Gone

Миграция с V1 на V2

Основные изменения

Редизайн REST API — Более чистые эндпоинты ресурсов
Формат ответа — Единая обертка, улучшенная обработка ошибок
Аутентификация — Добавлена поддержка OAuth 2.0 (API-ключи по-прежнему работают)
Ограничение запросов — Улучшенная детализация и ясность
Вебхуки — Переработанный формат событий и подпись

Сопоставление эндпоинтов

Эндпоинт V1	Эндпоинт V2	Изменения
GET /whales	GET /v2/whales/tracking	Реорганизовано, добавлена фильтрация
GET /funding	GET /v2/derivatives/funding-heatmap	Обязательный параметр биржи
GET /positions	GET /v2/derivatives/positions	Новые опции агрегации

Изменения в эндпоинтах

Изменения параметров запроса

Запрос V1
// V1: Ставки фандинга
GET /v1/funding?symbol=BTCUSDT&exchange=binance

Запрос V2
// V2: Те же данные, более четкая структура
GET /v2/derivatives/funding-heatmap?
  symbol=BTCUSDT&
  exchange=binance

Обновления формата ответа

Структура ответа V1

Формат V1
{
 "status": "success",
 "data": {
 "symbol": "BTCUSDT",
 "funding": 0.0001
  }
}

Структура ответа V2

Формат V2
{
 "data": {
 "symbol": "BTCUSDT",
 "funding_rate": 0.0001
  },
 "_meta": {
 "request_id": "req_abc123",
 "timestamp": 1709980800000
  }
}

Ключевые отличия: Нет обертки status, более понятные названия полей, стандартизированные метаданные.

График прекращения поддержки

Запланированные устаревания

Функция	Анонсировано	Дата прекращения	Замена
/v1/whales	Jan 2026	Jan 2028	/v2/whales/tracking
/v1/funding	Jan 2026	Jan 2028	/v2/derivatives/funding-heatmap
Аутентификация только по API-ключу	Mar 2026	Mar 2027	OAuth 2.0 (ключи по-прежнему работают)
Формат вебхука v1	Q2 2026	Q2 2027	Формат вебхука v2

Подробности критических изменений

Удаленные эндпоинты

/v1/stats — Заменен на /v2/metrics
/v1/historical — Заменен на /v2/historical с новыми параметрами
/v1/alerts/create — Заменен на POST /v2/alerts

Изменения параметров

limit — Значение по умолчанию изменено с 100 на 20 (указывайте явно!)
timeframe — Теперь обязателен для исторических запросов
sort — Формат изменен с "field asc" на "field:asc"

Изменения полей ответа

funding → funding_rate
price → mark_price
vol → volume_quote

Пошаговая миграция

Этап 1: Планирование (1-2 неделя)

Аудит текущей интеграции на предмет устаревших функций
Сопоставление эндпоинтов v1 с аналогами v2
Определение критических изменений, влияющих на ваш код
Планирование стратегии тестирования и сроков

Этап 2: Разработка (3-4 неделя)

Создание ветки v2 в системе контроля версий
Обновление всех API-эндпоинтов на URL v2
Обновление обработки запросов и ответов
Запуск модульных тестов в песочнице

Этап 3: Тестирование (5-6 неделя)

Запуск полного набора интеграционных тестов
Тестирование сценариев ошибок и граничных случаев
Нагрузочное тестирование с эндпоинтами v2
Аудит безопасности обновленного кода

Этап 4: Стенд (7 неделя)

Развертывание кода v2 на тестовой среде
Запуск полных приемочных тестов
Подтверждение заинтересованными сторонами
Подготовка плана отката

Этап 5: Продакшен (8 неделя)

Сине-зеленое развертывание в продакшен
Мониторинг метрик и уровня ошибок
Готовность к поддержке в случае проблем
Постепенное отключение кода v1

Поддержка и ресурсы

Доступные инструменты

Валидатор миграции — Проверка кода на устаревшее использование
Проверка обновления API — Сравнение совместимости v1 и v2
Чеклист миграции — PDF с задачами и сроками
Примеры кода — Примеры до и после миграции

Получение помощи

Email: [email protected]
Документация: см. changelog-versioning.html
Discord: Канал поддержки сообщества
Enterprise: Выделенный инженер по миграции

Начните миграцию сегодня

Обновитесь до API v2 с полным набором инструментов миграции, документацией и поддержкой. Разработано для миграции без простоев.

Изучите V2

V1 поддерживается до Jan 2028. Запланируйте миграцию сегодня.