Indice dei Contenuti

Panoramica Politica di Versionamento Compatibilità con le Versioni Precedenti Migrazione da V1 a V2 Modifiche agli Endpoint Aggiornamenti al Formato di Risposta Cronologia di Deprecazione Modifiche Non Compatibili Migrazione Passo-Passo Supporto e Risorse

Documentazione API

Guida alla Migrazione API — Aggiornamento tra Versioni

Pianifica ed esegui aggiornamenti fluidi tra versioni API. Comprendi le modifiche non compatibili, le tempistiche di deprecazione e le migliori pratiche per migrare tra le versioni di Smart Money API.

Pubblicato il 21 marzo 2026 • 16 min di lettura • Avanzato

Panoramica della Migrazione

Smart Money API è in costante sviluppo con aggiornamenti regolari. Questa guida copre la gestione delle versioni, le modifiche non compatibili e come migrare la tua integrazione senza tempi di inattività.

Principi chiave della migrazione:

Versionamento Semantico — Formato MAJOR.MINOR.PATCH rigorosamente seguito
Supporto a Lungo Termine — La versione major precedente è supportata per 24+ mesi
Avvisi di Deprecazione — Preavviso di 6 mesi per tutte le modifiche non compatibili
Versioni Parallele — Esegui v1 e v2 simultaneamente durante la migrazione
Test Automatici — Strumenti di compatibilità per suite di test forniti

Stato Attuale: v1 (attuale), v2 (beta, disponibilità generale Q2 2026). v1 supportata fino al Q1 2028.

Politica di Versionamento

Versionamento Semantico

Formato della Versione
Versione API: MAJOR.MINOR.PATCH
Esempio: 2.1.3
MAJOR (2) - Modifiche non compatibili, nuova architettura
MINOR (1) - Funzionalità compatibili con le versioni precedenti
PATCH (3) - Correzione di bug, aggiornamenti di sicurezza

Ciclo di Rilascio delle Versioni

Fase	Durata	Caratteristiche
Alpha	2-4 settimane	Modifiche non compatibili frequenti, solo per testing
Beta	4-8 settimane	Principalmente stabile, feedback della community
Release Candidate	2-4 settimane	Pronto per la produzione, rifiniture finali
Disponibilità Generale	24+ mesi	Supporto completo per la produzione

Ottieni la tua API key in 30 secondi

Pronto a sviluppare? Ottieni una API key gratuita (200 chiamate/giorno, senza carta) e inizia a recuperare dati live su whale, funding e on-chain.

Ottieni la tua API key →

Compatibilità con le Versioni Precedenti

Compatibilità tra Versioni

All'interno di una versione major, puoi sempre aggiornare in sicurezza a versioni minor/patch più recenti:

URL degli Endpoint — Rimangono invariati
Campi Obbligatori — Mai rimossi (solo nuovi campi opzionali aggiunti)
Codici di Stato HTTP — Conservati per gli scenari esistenti
Struttura della Risposta — I campi principali rimangono identici
Autenticazione — Nessuna modifica ai meccanismi di autenticazione

Deprecazione Graduale

Cronologia di Deprecazione
// Mese 1: Annuncio di deprecazione
// Funzionalità marcata con intestazione Deprecation
Deprecation: version="2.2", sunset="2026-09-01"
// Mese 3-6: Periodo attivo di deprecazione
// L'API restituisce avvisi ma funziona ancora
X-Deprecation-Warning: Questo endpoint sarà rimosso il 2026-09-01
// Mese 6: Rimozione definitiva
// L'endpoint restituisce 410 Gone
HTTP/1.1 410 Gone

Migrazione da V1 a V2

Modifiche Principali

Riprogettazione dell'API REST — Endpoint delle risorse più puliti
Formato di Risposta — Wrapping consistente, migliore gestione degli errori
Autenticazione — Aggiunto supporto OAuth 2.0 (le API key funzionano ancora)
Limitazione delle Richieste — Migliorata granularità e chiarezza
Webhooks — Formato degli eventi e firma riprogettati

Mappatura degli Endpoint

Endpoint V1	Endpoint V2	Modifiche
GET /whales	GET /v2/whales/tracking	Riorganizzato, aggiunto filtraggio
GET /funding	GET /v2/derivatives/funding-heatmap	Parametro exchange obbligatorio
GET /positions	GET /v2/derivatives/positions	Nuove opzioni di aggregazione

Modifiche agli Endpoint

Modifiche ai Parametri di Richiesta

Richiesta V1
// V1: Tassi di funding
GET /v1/funding?symbol=BTCUSDT&exchange=binance

Richiesta V2
// V2: Stessi dati, struttura più chiara
GET /v2/derivatives/funding-heatmap?
  symbol=BTCUSDT&
  exchange=binance

Aggiornamenti al Formato di Risposta

Struttura della risposta V1

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

Struttura della risposta V2

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

Differenze chiave: Nessun wrapper di stato, nomi di campo più chiari, metadati standardizzati.

Cronologia di deprecazione

Deprecazioni pianificate

Funzionalità	Annunciato	Data di sunset	Sostituzione
/v1/whales	Gen 2026	Gen 2028	/v2/whales/tracking
/v1/funding	Gen 2026	Gen 2028	/v2/derivatives/funding-heatmap
Autenticazione solo con API key	Mar 2026	Mar 2027	OAuth 2.0 (le chiavi funzionano ancora)
Formato Webhook v1	Q2 2026	Q2 2027	Formato Webhook v2

Dettagli delle modifiche di rottura

Endpoint rimossi

/v1/stats — Sostituito da /v2/metrics
/v1/historical — Sostituito da /v2/historical con nuovi parametri
/v1/alerts/create — Sostituito da POST /v2/alerts

Modifiche ai parametri

limit — Valore predefinito cambiato da 100 a 20 (sii esplicito!)
timeframe — Ora obbligatorio per le query storiche
sort — Formato cambiato da "field asc" a "field:asc"

Modifiche ai campi della risposta

funding → funding_rate
price → mark_price
vol → volume_quote

Migrazione passo dopo passo

Fase 1: Pianificazione (Settimana 1-2)

Verifica l'integrazione esistente per funzionalità deprecate
Mappa gli endpoint v1 agli equivalenti v2
Identifica le modifiche di rottura che influiscono sul tuo codice
Pianifica la strategia di test e la tempistica

Fase 2: Sviluppo (Settimana 3-4)

Crea un branch v2 nel controllo di versione
Aggiorna tutti gli endpoint API agli URL v2
Aggiorna la gestione delle richieste/risposte
Esegui test unitari sul sandbox

Fase 3: Test (Settimana 5-6)

Esegui la suite completa di test di integrazione
Testa scenari di errore e casi limite
Test di carico con endpoint v2
Audit di sicurezza del codice aggiornato

Fase 4: Staging (Settimana 7)

Distribuisci il codice v2 nell'ambiente di staging
Esegui test di accettazione completi
Ottieni l'approvazione degli stakeholder
Prepara un piano di rollback

Fase 5: Produzione (Settimana 8)

Distribuzione blue-green in produzione
Monitora le metriche e i tassi di errore
Rimani disponibile per problemi di supporto
Disattiva gradualmente il codice v1

Supporto e risorse

Strumenti disponibili

Validatore di migrazione — Controlla il codice per utilizzi deprecati
API Upgrade Checker — Confronta la compatibilità tra v1 e v2
Checklist di migrazione — PDF con attività e tempistiche
Esempi di codice — Campioni prima/dopo la migrazione

Ottenere aiuto

Email: [email protected]
Documentazione: Vedi changelog-versioning.html
Discord: Canale di supporto della community
Enterprise: Ingegnere di migrazione dedicato

Inizia la tua migrazione oggi

Passa all'API v2 con strumenti di migrazione completi, documentazione e supporto. Progettato per supportare una migrazione senza tempi di inattività.

Esplora V2

V1 supportato fino a Gen 2028. Pianifica la tua migrazione oggi.