Spis treści

Przegląd Polityka wersjonowania Zgodność wsteczna Migracja z V1 do V2 Zmiany w endpointach Aktualizacje formatu odpowiedzi Harmonogram wycofywania Zmiany niezgodne wstecz Migracja krok po kroku Wsparcie i zasoby

Dokumentacja API

Przewodnik migracji API — Aktualizacja między wersjami

Zaplanuj i przeprowadź płynne aktualizacje wersji API. Zrozum zmiany niezgodne wstecz, harmonogramy wycofywania i najlepsze praktyki migracji między wersjami Smart Money API.

Opublikowano 21 marca 2026 • 16 minut czytania • Zaawansowane

Przegląd migracji

Smart Money API jest aktywnie rozwijany z regularnymi aktualizacjami. Ten przewodnik obejmuje zarządzanie wersjami, zmiany niezgodne wstecz oraz jak przeprowadzić migrację integracji bez przestojów.

Kluczowe zasady migracji:

Wersjonowanie semantyczne — Ścisłe przestrzeganie formatu MAJOR.MINOR.PATCH
Długoterminowe wsparcie — Poprzednia wersja major wspierana przez 24+ miesięcy
Ostrzeżenia o wycofaniu — 6-miesięczne wyprzedzenie dla wszystkich zmian niezgodnych wstecz
Wersje równoległe — Uruchomienie v1 i v2 jednocześnie podczas migracji
Testy automatyczne — Dostarczone narzędzia do testowania zgodności

Aktualny status: v1 (obecna), v2 (beta, ogólna dostępność Q2 2026). v1 wspierana do Q1 2028.

Polityka wersjonowania

Wersjonowanie semantyczne

Format wersji
Wersja API: MAJOR.MINOR.PATCH
Przykład: 2.1.3
MAJOR (2) - Zmiany niezgodne wstecz, nowa architektura
MINOR (1) - Funkcje zgodne wstecz
PATCH (3) - Poprawki błędów, aktualizacje bezpieczeństwa

Cykl wydania wersji

Faza	Czas trwania	Charakterystyka
Alpha	2-4 tygodnie	Duże zmiany niezgodne wstecz, tylko testy
Beta	4-8 tygodni	W większości stabilna, opinie społeczności
Release Candidate	2-4 tygodnie	Gotowa do produkcji, ostateczne poprawki
Ogólna dostępność	24+ miesięcy	Pełne wsparcie produkcyjne

Uzyskaj klucz API w 30 sekund

Gotowy do budowania? Zdobądź darmowy klucz API (200 wywołań/dzień, bez karty) i zacznij pobierać dane o wielorybach, finansowaniu i danych on-chain.

Uzyskaj klucz API →

Zgodność wsteczna

Zgodność wersji

W obrębie wersji major zawsze możesz bezpiecznie aktualizować do nowszych wersji minor/patch:

URL endpointów — Pozostają niezmienione
Wymagane pola — Nigdy nie usuwane (tylko nowe opcjonalne pola dodawane)
Kody statusu HTTP — Zachowane dla istniejących scenariuszy
Struktura odpowiedzi — Główne pola pozostają identyczne
Uwierzytelnianie — Brak zmian w mechanizmach uwierzytelniania

Stopniowe wycofywanie

Harmonogram wycofywania
// Miesiąc 1: Ogłoszenie wycofania
// Funkcja oznaczona nagłówkiem Deprecation
Deprecation: version="2.2", sunset="2026-09-01"
// Miesiąc 3-6: Aktywny okres wycofywania
// API zwraca ostrzeżenia, ale nadal działa
X-Deprecation-Warning: Ten endpoint zostanie usunięty 2026-09-01
// Miesiąc 6: Ostateczne usunięcie
// Endpoint zwraca 410 Gone
HTTP/1.1 410 Gone

Migracja z V1 do V2

Główne zmiany

Przebudowa REST API — Czystsze endpointy zasobów
Format odpowiedzi — Spójne opakowanie, lepsza obsługa błędów
Uwierzytelnianie — Dodane wsparcie OAuth 2.0 (klucze API nadal działają)
Limitowanie zapytań — Lepsza szczegółowość i przejrzystość
Webhooki — Przebudowany format zdarzeń i podpisywanie

Mapowanie endpointów

Endpoint V1	Endpoint V2	Zmiany
GET /whales	GET /v2/whales/tracking	Przebudowane, dodane filtrowanie
GET /funding	GET /v2/derivatives/funding-heatmap	Wymagany parametr giełdy
GET /positions	GET /v2/derivatives/positions	Nowe opcje agregacji

Zmiany w endpointach

Zmiany parametrów żądania

Żądanie V1
// V1: Stopy finansowania
GET /v1/funding?symbol=BTCUSDT&exchange=binance

Żądanie V2
// V2: Te same dane, klarowniejsza struktura
GET /v2/derivatives/funding-heatmap?
  symbol=BTCUSDT&
  exchange=binance

Aktualizacje formatu odpowiedzi

Struktura odpowiedzi V1

Format V1
{
 "status": "success",
 "data": {
 "symbol": "BTCUSDT",
 "funding": 0.0001
  }
}

Struktura odpowiedzi V2

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

Kluczowe różnice: Brak opakowania statusu, jaśniejsze nazwy pól, standaryzowane metadane.

Harmonogram wycofywania

Planowane wycofania

Funkcja	Ogłoszono	Data wycofania	Zastąpienie
/v1/whales	Jan 2026	Jan 2028	/v2/whales/tracking
/v1/funding	Jan 2026	Jan 2028	/v2/derivatives/funding-heatmap
Uwierzytelnianie tylko kluczem API	Mar 2026	Mar 2027	OAuth 2.0 (klucze nadal działają)
Format Webhook v1	Q2 2026	Q2 2027	Format Webhook v2

Szczegóły zmian niekompatybilnych

Usunięte punkty końcowe

/v1/stats — Zastąpione przez /v2/metrics
/v1/historical — Zastąpione przez /v2/historical z nowymi parametrami
/v1/alerts/create — Zastąpione przez POST /v2/alerts

Zmiany parametrów

limit — Domyślna wartość zmieniona z 100 na 20 (bądź explicite!)
timeframe — Teraz wymagane w zapytaniach historycznych
sort — Format zmieniony z "field asc" na "field:asc"

Zmiany pól odpowiedzi

funding → funding_rate
price → mark_price
vol → volume_quote

Migracja krok po kroku

Faza 1: Planowanie (tydzień 1-2)

Przeprowadź audyt istniejącej integracji pod kątem przestarzałych funkcji
Zmapuj punkty końcowe v1 na odpowiedniki v2
Zidentyfikuj zmiany niekompatybilne wpływające na twój kod
Zaplanuj strategię testowania i harmonogram

Faza 2: Rozwój (tydzień 3-4)

Utwórz gałąź v2 w systemie kontroli wersji
Zaktualizuj wszystkie punkty końcowe API na adresy URL v2
Zaktualizuj obsługę żądań/odpowiedzi
Przeprowadź testy jednostkowe na środowisku testowym

Faza 3: Testowanie (tydzień 5-6)

Przeprowadź pełny zestaw testów integracyjnych
Przetestuj scenariusze błędów i przypadki brzegowe
Testy obciążeniowe z punktami końcowymi v2
Audyt bezpieczeństwa zaktualizowanego kodu

Faza 4: Staging (tydzień 7)

Wdróż kod v2 w środowisku stagingowym
Przeprowadź pełne testy akceptacyjne
Uzyskaj zatwierdzenie od interesariuszy
Przygotuj plan wycofania

Faza 5: Produkcja (tydzień 8)

Wdrożenie blue-green w produkcji
Monitoruj metryki i wskaźniki błędów
Bądź dostępny na wezwanie w przypadku problemów
Stopniowo wycofuj kod v1

Wsparcie i zasoby

Dostępne narzędzia

Walidator migracji — Sprawdź kod pod kątem przestarzałego użycia
Sprawdzacz aktualizacji API — Porównaj kompatybilność v1 i v2
Lista kontrolna migracji — PDF z zadaniami i harmonogramem
Przykłady kodu — Przykłady przed i po migracji

Uzyskiwanie pomocy

Email: [email protected]
Dokumentacja: Zobacz changelog-versioning.html
Discord: Kanał wsparcia społeczności
Enterprise: Dedykowany inżynier migracji

Rozpocznij migrację już dziś

Zaktualizuj do API v2 z kompleksowymi narzędziami migracyjnymi, dokumentacją i wsparciem. Zaprojektowane do migracji bez przestojów.

Poznaj V2

V1 obsługiwane do Jan 2028. Zaplanuj swoją migrację już dziś.