Зміст

Огляд Політика версіонування Зворотна сумісність Міграція з V1 на V2 Зміни в ендпоінтах Оновлення формату відповіді Графік застарівання Критичні зміни Покрокова міграція Підтримка та ресурси

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

API Migration Guide — Upgrading Between Versions

Плануйте та виконуйте плавні оновлення версій 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 (ключі все ще працюють)
Формат Webhook v1	Q2 2026	Q2 2027	Формат Webhook 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)

Blue-green розгортання у продуктивному середовищі
Моніторинг метрик та рівня помилок
Готовність до вирішення проблем
Поступове виведення коду v1

Підтримка та ресурси

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

Валідатор міграції — Перевірка коду на використання застарілих функцій
Перевірка сумісності API — Порівняння сумісності v1 та v2
Контрольний список міграції — PDF із завданнями та термінами
Приклади коду — Зразки до та після міграції

Отримання допомоги

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

Почніть міграцію вже сьогодні

Оновіться до API v2 з комплексними інструментами міграції, документацією та підтримкою. Розроблено для міграції без простоїв.

Дослідіть V2

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