Table des matières

Aperçu Politique de versionnage Compatibilité ascendante Migration de V1 à V2 Changements des points de terminaison Mises à jour du format de réponse Calendrier de dépréciation Changements cassants Migration étape par étape Support & Ressources

Documentation de l'API

Guide de migration de l'API — Mise à niveau entre les versions

Planifiez et exécutez des mises à niveau fluides des versions de l'API. Comprenez les changements cassants, les calendriers de dépréciation et les meilleures pratiques pour migrer entre les versions de Smart Money API.

Publié le 21 mars 2026 • 16 min de lecture • Avancé

Aperçu de la migration

Smart Money API est activement développé avec des mises à jour régulières. Ce guide couvre la gestion des versions, les changements cassants et comment migrer votre intégration sans temps d'arrêt.

Principes clés de la migration :

Versionnage sémantique — Format MAJOR.MINOR.PATCH strictement suivi
Support à long terme — La version majeure précédente est supportée pendant 24 mois ou plus
Avertissements de dépréciation — Préavis de 6 mois pour tous les changements cassants
Versions parallèles — Exécutez v1 et v2 simultanément pendant la migration
Tests automatisés — Outils de compatibilité de suite de tests fournis

Statut actuel : v1 (actuelle), v2 (bêta, disponibilité générale Q2 2026). v1 supportée jusqu'au Q1 2028.

Politique de versionnage

Versionnage sémantique

Format de version
Version de l'API : MAJOR.MINOR.PATCH
Exemple : 2.1.3
MAJOR (2) - Changements cassants, nouvelle architecture
MINOR (1) - Fonctionnalités compatibles ascendantes
PATCH (3) - Corrections de bugs, mises à jour de sécurité

Cycle de sortie des versions

Phase	Durée	Caractéristiques
Alpha	2-4 semaines	Changements cassants importants, tests uniquement
Bêta	4-8 semaines	Principalement stable, retour de la communauté
Candidat à la version	2-4 semaines	Prêt pour la production, finitions finales
Disponibilité générale	24+ mois	Support complet en production

Obtenez votre clé API en 30 secondes

Prêt à construire ? Obtenez une clé API gratuite (200 appels/jour, sans carte) et commencez à extraire des données en direct sur les baleines, le financement et les données on-chain.

Obtenez votre clé API →

Compatibilité ascendante

Compatibilité des versions

Au sein d'une version majeure, vous pouvez toujours passer en toute sécurité à des versions mineures/patches plus récentes :

URL des points de terminaison — Restent inchangées
Champs obligatoires — Jamais supprimés (seuls de nouveaux champs optionnels sont ajoutés)
Codes de statut HTTP — Conservés pour les scénarios existants
Structure de réponse — Les champs principaux restent identiques
Authentification — Aucun changement sur les mécanismes d'authentification

Dépréciation progressive

Calendrier de dépréciation
// Mois 1 : Annonce de la dépréciation
// Fonctionnalité marquée avec l'en-tête Deprecation
Deprecation: version="2.2", sunset="2026-09-01"
// Mois 3-6 : Période de dépréciation active
// L'API retourne des avertissements mais fonctionne toujours
X-Deprecation-Warning: Ce point de terminaison sera supprimé le 2026-09-01
// Mois 6 : Suppression finale
// Le point de terminaison retourne 410 Gone
HTTP/1.1 410 Gone

Migration de V1 à V2

Changements majeurs

Redesign de l'API REST — Points de terminaison de ressources plus propres
Format de réponse — Enveloppe cohérente, meilleure gestion des erreurs
Authentification — Support OAuth 2.0 ajouté (les clés API fonctionnent toujours)
Limitation de débit — Granularité et clarté améliorées
Webhooks — Format d'événement et signature redessinés

Correspondance des points de terminaison

Point de terminaison v1	Point de terminaison v2	Changements
GET /whales	GET /v2/whales/tracking	Réorganisé, filtrage ajouté
GET /funding	GET /v2/derivatives/funding-heatmap	Paramètre d'échange requis
GET /positions	GET /v2/derivatives/positions	Nouvelles options d'agrégation

Changements des points de terminaison

Changements des paramètres de requête

Requête V1
// V1 : Taux de financement
GET /v1/funding?symbol=BTCUSDT&exchange=binance

Requête V2
// V2 : Mêmes données, structure plus claire
GET /v2/derivatives/funding-heatmap?
  symbol=BTCUSDT&
  exchange=binance

Mises à jour du format de réponse

Structure de réponse V1

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

Structure de réponse V2

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

Différences clés : Pas d'enveloppe de statut, noms de champs plus clairs, métadonnées standardisées.

Calendrier de dépréciation

Dépréciations planifiées

Fonctionnalité	Annoncée	Date de fin de support	Remplacement
/v1/whales	Jan 2026	Jan 2028	/v2/whales/tracking
/v1/funding	Jan 2026	Jan 2028	/v2/derivatives/funding-heatmap
Authentification par clé API uniquement	Mar 2026	Mar 2027	OAuth 2.0 (les clés restent valables)
Format Webhook v1	Q2 2026	Q2 2027	Format Webhook v2

Détails des changements cassants

Endpoints supprimés

/v1/stats — Remplacé par /v2/metrics
/v1/historical — Remplacé par /v2/historical avec nouveaux paramètres
/v1/alerts/create — Remplacé par POST /v2/alerts

Changements de paramètres

limit — Valeur par défaut passée de 100 à 20 (soyez explicite !)
timeframe — Maintenant obligatoire pour les requêtes historiques
sort — Format changé de "field asc" à "field:asc"

Changements de champs de réponse

funding → funding_rate
price → mark_price
vol → volume_quote

Migration étape par étape

Phase 1 : Planification (Semaine 1-2)

Auditer l'intégration existante pour les fonctionnalités dépréciées
Mapper les endpoints v1 vers leurs équivalents v2
Identifier les changements cassants affectant votre code
Planifier la stratégie de test et le calendrier

Phase 2 : Développement (Semaine 3-4)

Créer une branche v2 dans le contrôle de version
Mettre à jour tous les endpoints API vers les URLs v2
Mettre à jour la gestion des requêtes/réponses
Exécuter les tests unitaires sur l'environnement sandbox

Phase 3 : Tests (Semaine 5-6)

Exécuter la suite complète de tests d'intégration
Tester les scénarios d'erreur et les cas limites
Tests de charge avec les endpoints v2
Audit de sécurité du code mis à jour

Phase 4 : Mise en staging (Semaine 7)

Déployer le code v2 en environnement de staging
Exécuter les tests d'acceptation complets
Obtenir l'approbation des parties prenantes
Préparer un plan de retour arrière

Phase 5 : Production (Semaine 8)

Déploiement blue-green en production
Surveiller les métriques et les taux d'erreur
Rester en support pour les problèmes éventuels
Décommissionner progressivement le code v1

Support & Ressources

Outils disponibles

Validateur de migration — Vérifier le code pour les usages dépréciés
Vérificateur de mise à niveau API — Comparer la compatibilité entre v1 et v2
Checklist de migration — PDF avec tâches et calendrier
Exemples de code — Avant/après migration

Obtenir de l'aide

Email : [email protected]
Documentation : Voir changelog-versioning.html
Discord : Canal de support communautaire
Entreprise : Ingénieur de migration dédié

Commencez votre migration dès aujourd'hui

Passez à l'API v2 avec des outils de migration complets, une documentation et un support. Conçu pour une migration sans temps d'arrêt.

Explorer V2

V1 supportée jusqu'en Jan 2028. Planifiez votre migration dès aujourd'hui.