Obsah

Přehled Zásady verzování Zpětná kompatibilita Migrace z V1 na V2 Změny endpointů Aktualizace formátu odpovědí Časový plán zastarávání Změny způsobující nekompatibilitu Migrace krok za krokem Podpora a zdroje

Dokumentace API

API Migration Guide — Upgrading Between Versions

Naplánujte a proveďte bezproblémové aktualizace verzí API. Pochopte změny způsobující nekompatibilitu, časové plány zastarávání a osvědčené postupy pro migraci mezi verzemi Smart Money API.

Publikováno 21. března 2026 • 16 minut čtení • Pokročilé

Přehled migrace

Smart Money API se aktivně vyvíjí s pravidelnými aktualizacemi. Tato příručka pokrývá správu verzí, změny způsobující nekompatibilitu a jak migrovat vaši integraci bez výpadků.

Klíčové principy migrace:

Sémantické verzování — Formát MAJOR.MINOR.PATCH striktně dodržován
Dlouhodobá podpora — Předchozí hlavní verze podporována 24+ měsíců
Varování před zastaráváním — 6měsíční předstižné upozornění na všechny změny způsobující nekompatibilitu
Paralelní verze — Spouštějte v1 a v2 současně během migrace
Automatizované testování — Poskytovány nástroje pro kompatibilitu testovací sady

Aktuální stav: v1 (aktuální), v2 (beta, obecná dostupnost Q2 2026). v1 podporována do Q1 2028.

Zásady verzování

Sémantické verzování

Formát verze
Verze API: MAJOR.MINOR.PATCH
Příklad: 2.1.3
MAJOR (2) - Změny způsobující nekompatibilitu, nová architektura
MINOR (1) - Zpětně kompatibilní funkce
PATCH (3) - Opravy chyb, bezpečnostní aktualizace

Cyklus vydávání verzí

Fáze	Trvání	Charakteristiky
Alpha	2-4 týdny	Významné změny způsobující nekompatibilitu, pouze testování
Beta	4-8 týdnů	Převážně stabilní, zpětná vazba komunity
Release Candidate	2-4 týdnů	Připraveno pro produkci, finální úpravy
General Availability	24+ měsíců	Plná produkční podpora

Získejte svůj API klíč za 30 sekund

Připraveni stavět? Získejte zdarma API klíč (200 volání/den, bez karty) a začněte stahovat živá data o velrybách, financování a on-chain datech.

Získejte svůj API klíč →

Zpětná kompatibilita

Kompatibilita verzí

V rámci hlavní verze můžete vždy bezpečně upgradovat na novější minor/patch verze:

URL endpointů — Zůstávají nezměněny
Povinná pole — Nikdy neodstraňována (přidávána pouze nová volitelná pole)
HTTP stavové kódy — Zachovány pro existující scénáře
Struktura odpovědi — Základní pole zůstávají stejná
Autentizace — Žádné změny v autentizačních mechanismech

Postupné zastarávání

Časový plán zastarávání
// Měsíc 1: Oznámení zastarávání
// Funkce označena hlavičkou Deprecation
Deprecation: version="2.2", sunset="2026-09-01"
// Měsíc 3-6: Aktivní období zastarávání
// API vrací varování, ale stále funguje
X-Deprecation-Warning: Tento endpoint bude odstraněn 2026-09-01
// Měsíc 6: Konečné odstranění
// Endpoint vrací 410 Gone
HTTP/1.1 410 Gone

Migrace z V1 na V2

Hlavní změny

Redesign REST API — Čistější endpointy zdrojů
Formát odpovědi — Konzistentní zabalení, lepší zpracování chyb
Autentizace — Přidána podpora OAuth 2.0 (API klíče stále fungují)
Omezení rychlosti — Vylepšená granularita a přehlednost
Webhooky — Přepracovaný formát událostí a podepisování

Mapování endpointů

Endpoint V1	Endpoint V2	Změny
GET /whales	GET /v2/whales/tracking	Reorganizováno, přidáno filtrování
GET /funding	GET /v2/derivatives/funding-heatmap	Povinný parametr burzy
GET /positions	GET /v2/derivatives/positions	Nové možnosti agregace

Změny endpointů

Změny parametrů požadavku

Požadavek V1
// V1: Funding rates
GET /v1/funding?symbol=BTCUSDT&exchange=binance

Požadavek V2
// V2: Stejná data, jasnější struktura
GET /v2/derivatives/funding-heatmap?
  symbol=BTCUSDT&
  exchange=binance

Aktualizace formátu odpovědí

Struktura odpovědi V1

Formát V1
{
 "status": "success",
 "data": {
 "symbol": "BTCUSDT",
 "funding": 0.0001
  }
}

Struktura odpovědi V2

Formát V2
{
 "data": {
 "symbol": "BTCUSDT",
 "funding_rate": 0.0001
  },
 "_meta": {
 "request_id": "req_abc123",
 "timestamp": 1709980800000
  }
}

Klíčové rozdíly: Žádný obal stavu, jasnější názvy polí, standardizovaná metadata.

Časový plán ukončení podpory

Plánovaná ukončení podpory

Funkce	Oznámeno	Datum ukončení	Náhrada
/v1/whales	Jan 2026	Jan 2028	/v2/whales/tracking
/v1/funding	Jan 2026	Jan 2028	/v2/derivatives/funding-heatmap
Autentizace pouze pomocí API klíče	Bře 2026	Bře 2027	OAuth 2.0 (klíče stále fungují)
Formát webhooku v1	Q2 2026	Q2 2027	Formát webhooku v2

Podrobnosti o zásadních změnách

Odebrané endpointy

/v1/stats — Nahrazeno /v2/metrics
/v1/historical — Nahrazeno /v2/historical s novými parametry
/v1/alerts/create — Nahrazeno POST /v2/alerts

Změny parametrů

limit — Výchozí hodnota změněna z 100 na 20 (buďte explicitní!)
timeframe — Nyní povinné u historických dotazů
sort — Formát změněn z "field asc" na "field:asc"

Změny v polích odpovědi

funding → funding_rate
price → mark_price
vol → volume_quote

Postup migrace krok za krokem

Fáze 1: Plánování (týden 1-2)

Prozkoumejte stávající integraci na zastaralé funkce
Namapujte endpointy v1 na ekvivalenty v2
Identifikujte zásadní změny ovlivňující váš kód
Naplánujte strategii testování a časový harmonogram

Fáze 2: Vývoj (týden 3-4)

Vytvořte větev v2 ve verzovacím systému
Aktualizujte všechny API endpointy na URL v2
Aktualizujte zpracování požadavků a odpovědí
Spusťte jednotkové testy v sandboxu

Fáze 3: Testování (týden 5-6)

Spusťte kompletní sadu integračních testů
Otestujte chybové scénáře a hraniční případy
Testování zátěže s endpointy v2
Bezpečnostní audit aktualizovaného kódu

Fáze 4: Příprava (týden 7)

Nasaďte kód v2 do přípravného prostředí
Spusťte kompletní akceptační testy
Získejte schválení od zainteresovaných stran
Připravte plán návratu

Fáze 5: Produkce (týden 8)

Blue-green nasazení do produkce
Sledujte metriky a míru chyb
Buďte v pohotovosti pro podporu
Postupně vyřaďte kód v1

Podpora a zdroje

Dostupné nástroje

Validátor migrace — Zkontrolujte kód na zastaralé použití
Kontrola kompatibility API — Porovnejte kompatibilitu v1 a v2
Kontrolní seznam migrace — PDF s úkoly a časovým harmonogramem
Příklady kódu — Vzorky před a po migraci

Jak získat pomoc

Email: [email protected]
Dokumentace: Viz changelog-versioning.html
Discord: Komunitní podpůrný kanál
Enterprise: Vyhrazený migrační inženýr

Začněte s migrací ještě dnes

Upgradujte na API v2 s komplexními migračními nástroji, dokumentací a podporou. Navrženo pro migraci bez výpadků.

Prozkoumejte V2

V1 podporováno do Jan 2028. Naplánujte si migraci ještě dnes.