Isi Kandungan

Gambaran Keseluruhan Polisi Versi Keserasian Ke Belakang Migrasi V1 ke V2 Perubahan Endpoint Kemas Kini Format Respons Garis Masa Penamatan Perubahan Pemutus Migrasi Langkah demi Langkah Sokongan & Sumber

Dokumentasi API

Panduan Migrasi API — Menaik Taraf Antara Versi

Rancang dan laksanakan peningkatan versi API yang lancar. Fahami perubahan pemutus, garis masa penamatan, dan amalan terbaik untuk migrasi antara versi Smart Money API.

Diterbitkan pada 21 Mac 2026 • 16 min baca • Lanjutan

Gambaran Keseluruhan Migrasi

Smart Money API sedang dibangunkan secara aktif dengan kemas kini berkala. Panduan ini meliputi pengurusan versi, perubahan pemutus, dan cara migrasi integrasi anda tanpa downtime.

Prinsip utama migrasi:

Versi Semantik — Format MAJOR.MINOR.PATCH dipatuhi dengan ketat
Sokongan Jangka Panjang — Versi major sebelumnya disokong selama 24+ bulan
Amaran Penamatan — Notis awal 6 bulan untuk semua perubahan pemutus
Versi Selari — Jalankan v1 dan v2 serentak semasa migrasi
Ujian Automatik — Alat keserasian suite ujian disediakan

Status Semasa: v1 (semasa), v2 (beta, ketersediaan umum Q2 2026). v1 disokong sehingga Q1 2028.

Polisi Versi

Versi Semantik

Format Versi
Versi API: MAJOR.MINOR.PATCH
Contoh: 2.1.3
MAJOR (2) - Perubahan pemutus, seni bina baru
MINOR (1) - Ciri serasi ke belakang
PATCH (3) - Pembaikan pepijat, kemas kini keselamatan

Kitaran Pelepasan Versi

Fasa	Tempoh	Ciri-ciri
Alpha	2-4 minggu	Perubahan pemutus berat, ujian sahaja
Beta	4-8 minggu	Kebanyakannya stabil, maklum balas komuniti
Calon Pelepasan	2-4 minggu	Sedia untuk pengeluaran, kemasan akhir
Ketersediaan Umum	24+ bulan	Sokongan pengeluaran penuh

Dapatkan kunci API dalam 30 saat

Sedia untuk membina? Dapatkan kunci API percuma (100 panggilan/hari, tiada kad) dan mula menarik data paus, pembiayaan dan on-chain secara langsung.

Dapatkan kunci API →

Keserasian Ke Belakang

Keserasian Versi

Dalam versi major, anda sentiasa boleh menaik taraf ke versi minor/patch yang lebih baru dengan selamat:

URL Endpoint — Tidak berubah
Medan Wajib — Tidak pernah dikeluarkan (hanya medan pilihan baru ditambah)
Kod Status HTTP — Dipelihara untuk senario sedia ada
Struktur Respons — Medan teras tetap sama
Pengesahan — Tiada perubahan pada mekanisme auth

Penamatan Secara Beradab

Garis Masa Penamatan
// Bulan 1: Umumkan penamatan
// Ciri ditandakan dengan header Penamatan
Penamatan: version="2.2", sunset="2026-09-01"
// Bulan 3-6: Tempoh penamatan aktif
// API mengembalikan amaran tetapi masih berfungsi
X-Amaran-Penamatan: Endpoint ini akan dikeluarkan pada 2026-09-01
// Bulan 6: Penyingkiran akhir
// Endpoint mengembalikan 410 Gone
HTTP/1.1 410 Gone

Migrasi V1 ke V2

Perubahan Utama

Reka Bentuk Semula API REST — Endpoint sumber yang lebih bersih
Format Respons — Pembungkusan konsisten, pengendalian ralat yang lebih baik
Pengesahan — Sokongan OAuth 2.0 ditambah (kunci API masih berfungsi)
Had Kadar — Peningkatan granulariti dan kejelasan
Webhooks — Format dan penandatanganan acara yang direka semula

Pemetaan Endpoint

Endpoint V1	Endpoint V2	Perubahan
GET /whales	GET /v2/whales/tracking	Disusun semula, penapisan ditambah
GET /funding	GET /v2/derivatives/funding-heatmap	Parameter pertukaran diperlukan
GET /positions	GET /v2/derivatives/positions	Pilihan pengagregatan baru

Perubahan Endpoint

Perubahan Parameter Permintaan

Permintaan V1
// V1: Kadar pembiayaan
GET /v1/funding?symbol=BTCUSDT&exchange=binance

Permintaan V2
// V2: Data yang sama, struktur yang lebih jelas
GET /v2/derivatives/funding-heatmap?
  symbol=BTCUSDT&
  exchange=binance

Kemas Kini Format Respons

Struktur Respons V1

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

Struktur Respons V2

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

Perbezaan Utama: Tiada pembungkus status, nama medan lebih jelas, metadata piawai.

Garis Masa Penamatan

Penamatan yang Dijangka

Ciri	Diumumkan	Tarikh Tamat	Pengganti
/v1/whales	Jan 2026	Jan 2028	/v2/whales/tracking
/v1/funding	Jan 2026	Jan 2028	/v2/derivatives/funding-heatmap
Pengesahan kunci API sahaja	Mac 2026	Mac 2027	OAuth 2.0 (kunci masih berfungsi)
Format Webhook v1	Q2 2026	Q2 2027	Format Webhook v2

Perincian Perubahan Utama

Titik Akhir yang Dihapuskan

/v1/stats — Digantikan dengan /v2/metrics
/v1/historical — Digantikan dengan /v2/historical dengan parameter baru
/v1/alerts/create — Digantikan dengan POST /v2/alerts

Perubahan Parameter

limit — Lalai berubah dari 100 kepada 20 (nyatakan dengan jelas!)
timeframe — Kini diperlukan pada pertanyaan sejarah
sort — Format berubah dari "field asc" kepada "field:asc"

Perubahan Medan Respons

funding → funding_rate
price → mark_price
vol → volume_quote

Migrasi Langkah demi Langkah

Fasa 1: Perancangan (Minggu 1-2)

Audit integrasi sedia ada untuk ciri yang ditamatkan
Petakan titik akhir v1 kepada yang setara v2
Kenal pasti perubahan utama yang mempengaruhi kod anda
Rancang strategi dan garis masa ujian

Fasa 2: Pembangunan (Minggu 3-4)

Buat cabang v2 dalam kawalan versi
Kemaskini semua titik akhir API ke URL v2
Kemaskini pengendalian permintaan/respons
Jalankan ujian unit terhadap kotak pasir

Fasa 3: Pengujian (Minggu 5-6)

Jalankan suite ujian integrasi penuh
Uji senario ralat dan kes tepi
Ujian beban dengan titik akhir v2
Audit keselamatan kod yang dikemaskini

Fasa 4: Pentas (Minggu 7)

Laksanakan kod v2 ke persekitaran pentas
Jalankan ujian penerimaan penuh
Dapatkan persetujuan daripada pemegang kepentingan
Sediakan pelan pemulihan

Fasa 5: Pengeluaran (Minggu 8)

Pelaksanaan biru-hijau ke pengeluaran
Pantau metrik dan kadar ralat
Bersedia untuk isu sokongan
Secara beransur-ansur hentikan kod v1

Sokongan & Sumber

Alatan Tersedia

Pengesah Migrasi — Semak kod untuk penggunaan yang ditamatkan
Pemeriksa Naik Taraf API — Bandingkan keserasian v1 dan v2
Senarai Semak Migrasi — PDF dengan tugas dan garis masa
Contoh Kod — Contoh sebelum/selepas migrasi

Mendapatkan Bantuan

Emel: [email protected]
Dokumentasi: Lihat changelog-versioning.html
Discord: Saluran sokongan komuniti
Enterprise: Jurutera migrasi berdedikasi

Mulakan Migrasi Anda Hari Ini

Naik taraf ke API v2 dengan alatan migrasi yang komprehensif, dokumentasi, dan sokongan. Dibina untuk menyokong migrasi tanpa gangguan.

Terokai V2

V1 disokong sehingga Jan 2028. Rancang migrasi anda hari ini.