Inhaltsverzeichnis

Übersicht Versionsrichtlinie Abwärtskompatibilität Migration von V1 zu V2 Änderungen an Endpunkten Aktualisierungen des Antwortformats Zeitplan für Einstellung Breaking Changes Schritt-für-Schritt-Migration Support & Ressourcen

API-Dokumentation

API-Migrationsleitfaden – Upgrades zwischen Versionen

Planen und führen Sie reibungslose API-Versionsupgrades durch. Verstehen Sie Breaking Changes, Zeitpläne für Einstellungen und Best Practices für die Migration zwischen Smart Money API-Versionen.

Veröffentlicht am 21. März 2026 • 16 Min. Lesezeit • Fortgeschritten

Migrationsübersicht

Smart Money API wird aktiv weiterentwickelt mit regelmäßigen Updates. Dieser Leitfaden behandelt Versionsverwaltung, Breaking Changes und wie Sie Ihre Integration ohne Ausfallzeiten migrieren.

Wichtige Migrationsprinzipien:

Semantische Versionierung — MAJOR.MINOR.PATCH-Format wird strikt eingehalten
Langzeitunterstützung — Vorherige Major-Version wird 24+ Monate unterstützt
Veraltungshinweise — 6 Monate Vorlaufzeit bei allen Breaking Changes
Parallele Versionen — Führen Sie v1 und v2 gleichzeitig während der Migration aus
Automatisierte Tests — Kompatibilitätstest-Tools werden bereitgestellt

Aktueller Status: v1 (aktuell), v2 (Beta, allgemeine Verfügbarkeit Q2 2026). v1 wird bis Q1 2028 unterstützt.

Versionsrichtlinie

Semantische Versionierung

Versionsformat
API-Version: MAJOR.MINOR.PATCH
Beispiel: 2.1.3
MAJOR (2) - Breaking Changes, neue Architektur
MINOR (1) - Abwärtskompatible Funktionen
PATCH (3) - Bugfixes, Sicherheitsupdates

Versionsfreigabezyklus

Phase	Dauer	Merkmale
Alpha	2-4 Wochen	Häufige Breaking Changes, nur für Tests
Beta	4-8 Wochen	Größtenteils stabil, Community-Feedback
Release Candidate	2-4 Wochen	Produktionsreif, finale Überarbeitung
Allgemeine Verfügbarkeit	24+ Monate	Vollständige Produktionsunterstützung

API-Schlüssel in 30 Sekunden erhalten

Bereit zum Entwickeln? Holen Sie sich einen kostenlosen API-Schlüssel (200 Aufrufe/Tag, keine Karte) und starten Sie mit Live-Daten zu Walen, Funding und On-Chain-Daten.

API-Schlüssel erhalten →

Abwärtskompatibilität

Versionskompatibilität

Innerhalb einer Major-Version können Sie sicher auf neuere Minor-/Patch-Versionen upgraden:

Endpunkt-URLs — Bleiben unverändert
Erforderliche Felder — Werden nie entfernt (nur neue optionale Felder hinzugefügt)
HTTP-Statuscodes — Für bestehende Szenarien beibehalten
Antwortstruktur — Kernfelder bleiben identisch
Authentifizierung — Keine Änderungen an Authentifizierungsmechanismen

Geordnete Veraltung

Zeitplan für Einstellung
// Monat 1: Veraltung ankündigen
// Funktion mit Veraltungs-Header markiert
Deprecation: version="2.2", sunset="2026-09-01"
// Monat 3-6: Aktive Veraltungsphase
// API gibt Warnungen aus, funktioniert aber noch
X-Deprecation-Warning: Dieser Endpunkt wird am 2026-09-01 entfernt
// Monat 6: Endgültige Entfernung
// Endpunkt gibt 410 Gone zurück
HTTP/1.1 410 Gone

Migration von V1 zu V2

Wesentliche Änderungen

REST API-Redesign — Übersichtlichere Ressourcen-Endpunkte
Antwortformat — Konsistente Struktur, bessere Fehlerbehandlung
Authentifizierung — OAuth 2.0-Unterstützung hinzugefügt (API-Schlüssel funktionieren weiterhin)
Ratenbegrenzung — Verbesserte Granularität und Klarheit
Webhooks — Überarbeitetes Ereignisformat und Signierung

Endpunkt-Zuordnung

v1-Endpunkt	v2-Endpunkt	Änderungen
GET /whales	GET /v2/whales/tracking	Neu organisiert, Filterung hinzugefügt
GET /funding	GET /v2/derivatives/funding-heatmap	Exchange-Parameter erforderlich
GET /positions	GET /v2/derivatives/positions	Neue Aggregationsoptionen

Änderungen an Endpunkten

Änderungen an Anfrageparametern

V1-Anfrage
// V1: Funding Rates
GET /v1/funding?symbol=BTCUSDT&exchange=binance

V2-Anfrage
// V2: Gleiche Daten, klarere Struktur
GET /v2/derivatives/funding-heatmap?
  symbol=BTCUSDT&
  exchange=binance

Aktualisierungen des Antwortformats

V1 Antwortstruktur

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

V2 Antwortstruktur

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

Wichtige Unterschiede: Kein Status-Wrapper, klarere Feldnamen, standardisierte Metadaten.

Zeitplan für die Einstellung

Geplante Einstellungen

Funktion	Angekündigt	Einstellungsdatum	Ersatz
/v1/whales	Jan 2026	Jan 2028	/v2/whales/tracking
/v1/funding	Jan 2026	Jan 2028	/v2/derivatives/funding-heatmap
Nur API-Schlüssel-Authentifizierung	März 2026	März 2027	OAuth 2.0 (Schlüssel funktionieren weiterhin)
Webhook v1 Format	Q2 2026	Q2 2027	Webhook v2 Format

Details zu Breaking Changes

Entfernte Endpunkte

/v1/stats — Ersetzt durch /v2/metrics
/v1/historical — Ersetzt durch /v2/historical mit neuen Parametern
/v1/alerts/create — Ersetzt durch POST /v2/alerts

Parameteränderungen

limit — Standardwert von 100 auf 20 geändert (explizit angeben!)
timeframe — Jetzt bei historischen Abfragen erforderlich
sort — Format von "field asc" zu "field:asc" geändert

Änderungen an Antwortfeldern

funding → funding_rate
price → mark_price
vol → volume_quote

Schritt-für-Schritt-Migration

Phase 1: Planung (Woche 1-2)

Überprüfung der bestehenden Integration auf veraltete Funktionen
Zuordnung von v1-Endpunkten zu v2-Äquivalenten
Identifizierung von Breaking Changes, die Ihren Code betreffen
Planung der Teststrategie und des Zeitplans

Phase 2: Entwicklung (Woche 3-4)

Erstellen eines v2-Branches in der Versionskontrolle
Aktualisierung aller API-Endpunkte auf v2-URLs
Aktualisierung der Anfrage-/Antwortverarbeitung
Ausführen von Unit-Tests gegen die Sandbox

Phase 3: Testen (Woche 5-6)

Ausführen des vollständigen Integrationstest-Suites
Testen von Fehlerszenarien und Edge Cases
Lasttests mit v2-Endpunkten
Sicherheitsüberprüfung des aktualisierten Codes

Phase 4: Staging (Woche 7)

Bereitstellung des v2-Codes in der Staging-Umgebung
Ausführen vollständiger Akzeptanztests
Genehmigung durch Stakeholder einholen
Vorbereitung eines Rollback-Plans

Phase 5: Produktion (Woche 8)

Blue-Green-Deploy in der Produktion
Überwachung von Metriken und Fehlerraten
Bereitschaft für Supportprobleme
Schrittweise Außerbetriebnahme von v1-Code

Support & Ressourcen

Verfügbare Tools

Migrationsvalidator — Überprüfung des Codes auf veraltete Nutzung
API-Upgrade-Checker — Vergleich der v1- und v2-Kompatibilität
Migrations-Checkliste — PDF mit Aufgaben und Zeitplan
Codebeispiele — Vorher/Nachher-Migrationsbeispiele

Hilfe erhalten

E-Mail: [email protected]
Dokumentation: Siehe changelog-versioning.html
Discord: Community-Support-Kanal
Enterprise: Dedizierter Migrationsingenieur

Starten Sie Ihre Migration heute

Aktualisieren Sie auf API v2 mit umfassenden Migrationswerkzeugen, Dokumentation und Support. Entwickelt für eine Migration ohne Ausfallzeiten.

V2 erkunden

V1 wird bis Januar 2028 unterstützt. Planen Sie Ihre Migration heute.