Daftar Isi

Ikhtisar Kebijakan Versi Kompatibilitas Mundur Migrasi dari V1 ke V2 Perubahan Endpoint Pembaruan Format Respons Timeline Depresiasi Perubahan yang Bersifat Breaking Migrasi Langkah demi Langkah Dukungan & Sumber Daya

Dokumentasi API

API Migration Guide — Upgrading Between Versions

Rencanakan dan lakukan upgrade versi API dengan lancar. Pahami perubahan yang bersifat breaking, timeline depresiasi, dan praktik terbaik untuk migrasi antar versi Smart Money API.

Diterbitkan 21 Maret 2026 • 16 menit baca • Tingkat Lanjut

Ikhtisar Migrasi

Smart Money API terus dikembangkan dengan pembaruan rutin. Panduan ini mencakup manajemen versi, perubahan yang bersifat breaking, dan cara memigrasi integrasi Anda tanpa downtime.

Prinsip utama migrasi:

Semantic Versioning — Format MAJOR.MINOR.PATCH diikuti secara ketat
Dukungan Jangka Panjang — Versi mayor sebelumnya didukung selama 24+ bulan
Peringatan Depresiasi — Pemberitahuan 6 bulan sebelumnya untuk semua perubahan yang bersifat breaking
Versi Paralel — Jalankan v1 dan v2 secara bersamaan selama migrasi
Pengujian Otomatis — Alat kompatibilitas suite pengujian disediakan

Status Saat Ini: v1 (saat ini), v2 (beta, ketersediaan umum Q2 2026). v1 didukung hingga Q1 2028.

Kebijakan Versi

Semantic Versioning

Format Versi
Versi API: MAJOR.MINOR.PATCH
Contoh: 2.1.3
MAJOR (2) - Perubahan yang bersifat breaking, arsitektur baru
MINOR (1) - Fitur yang kompatibel ke belakang
PATCH (3) - Perbaikan bug, pembaruan keamanan

Siklus Rilis Versi

Fase	Durasi	Karakteristik
Alpha	2-4 minggu	Perubahan yang bersifat breaking besar, hanya untuk pengujian
Beta	4-8 minggu	Sebagian besar stabil, umpan balik komunitas
Release Candidate	2-4 minggu	Siap produksi, penyempurnaan akhir
General Availability	24+ bulan	Dukungan produksi penuh

Dapatkan kunci API dalam 30 detik

Siap membangun? Dapatkan kunci API gratis (100 panggilan/hari, tanpa kartu) dan mulai menarik data whale, funding, dan on-chain langsung.

Dapatkan kunci API →

Kompatibilitas Mundur

Kompatibilitas Versi

Dalam versi mayor, Anda selalu dapat upgrade ke versi minor/patch yang lebih baru dengan aman:

URL Endpoint — Tetap tidak berubah
Bidang Wajib — Tidak pernah dihapus (hanya bidang opsional baru yang ditambahkan)
Kode Status HTTP — Dipertahankan untuk skenario yang ada
Struktur Respons — Bidang inti tetap identik
Autentikasi — Tidak ada perubahan pada mekanisme autentikasi

Depresiasi yang Elegan

Timeline Depresiasi
// Bulan 1: Umumkan depresiasi
// Fitur ditandai dengan header Deprecation
Deprecation: version="2.2", sunset="2026-09-01"
// Bulan 3-6: Periode depresiasi aktif
// API mengembalikan peringatan tetapi masih berfungsi
X-Deprecation-Warning: Endpoint ini akan dihapus pada 2026-09-01
// Bulan 6: Penghapusan akhir
// Endpoint mengembalikan 410 Gone
HTTP/1.1 410 Gone

Migrasi dari V1 ke V2

Perubahan Utama

Desain Ulang REST API — Endpoint sumber daya yang lebih bersih
Format Respons — Pembungkusan yang konsisten, penanganan error yang lebih baik
Autentikasi — Dukungan OAuth 2.0 ditambahkan (kunci API masih berfungsi)
Pembatasan Laju — Granularitas dan kejelasan yang ditingkatkan
Webhooks — Format dan penandatanganan event yang didesain ulang

Pemetaan Endpoint

Endpoint V1	Endpoint V2	Perubahan
GET /whales	GET /v2/whales/tracking	Diatur ulang, ditambahkan penyaringan
GET /funding	GET /v2/derivatives/funding-heatmap	Parameter exchange wajib
GET /positions	GET /v2/derivatives/positions	Opsi agregasi baru

Perubahan Endpoint

Perubahan Parameter Permintaan

Permintaan V1
// V1: Funding rates
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

Pembaruan 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
  }
}

Perbedaan Utama: Tidak ada wrapper status, nama field lebih jelas, metadata standar.

Timeline Depresiasi

Depresiasi yang Direncanakan

Fitur	Diumumkan	Tanggal Sunset	Pengganti
/v1/whales	Jan 2026	Jan 2028	/v2/whales/tracking
/v1/funding	Jan 2026	Jan 2028	/v2/derivatives/funding-heatmap
Autentikasi hanya dengan API key	Mar 2026	Mar 2027	OAuth 2.0 (key masih bisa digunakan)
Format Webhook v1	Q2 2026	Q2 2027	Format Webhook v2

Detail Perubahan yang Bersifat Breaking

Endpoint yang Dihapus

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

Perubahan Parameter

limit — Default berubah dari 100 menjadi 20 (harus eksplisit!)
timeframe — Sekarang wajib untuk query historical
sort — Format berubah dari "field asc" menjadi "field:asc"

Perubahan Field Respons

funding → funding_rate
price → mark_price
vol → volume_quote

Migrasi Langkah demi Langkah

Fase 1: Perencanaan (Minggu 1-2)

Audit integrasi yang ada untuk fitur yang di-depresiasi
Petakan endpoint v1 ke padanan v2
Identifikasi perubahan breaking yang memengaruhi kode Anda
Rencanakan strategi dan timeline pengujian

Fase 2: Pengembangan (Minggu 3-4)

Buat branch v2 di version control
Perbarui semua endpoint API ke URL v2
Perbarui penanganan request/respons
Jalankan unit test di sandbox

Fase 3: Pengujian (Minggu 5-6)

Jalankan rangkaian pengujian integrasi lengkap
Uji skenario error dan edge case
Pengujian beban dengan endpoint v2
Audit keamanan kode yang diperbarui

Fase 4: Staging (Minggu 7)

Deploy kode v2 ke lingkungan staging
Jalankan pengujian penerimaan lengkap
Dapatkan persetujuan dari stakeholder
Siapkan rencana rollback

Fase 5: Produksi (Minggu 8)

Blue-green deploy ke produksi
Pantau metrik dan tingkat error
Siap siaga untuk masalah dukungan
Secara bertahap nonaktifkan kode v1

Dukungan & Sumber Daya

Alat yang Tersedia

Migration Validator — Periksa kode untuk penggunaan yang di-depresiasi
API Upgrade Checker — Bandingkan kompatibilitas v1 dan v2
Daftar Periksa Migrasi — PDF dengan tugas dan timeline
Contoh Kode — Contoh sebelum/sesudah migrasi

Mendapatkan Bantuan

Email: [email protected]
Dokumentasi: Lihat changelog-versioning.html
Discord: Saluran dukungan komunitas
Enterprise: Teknisi migrasi khusus

Mulai Migrasi Anda Hari Ini

Tingkatkan ke API v2 dengan alat migrasi, dokumentasi, dan dukungan lengkap. Dibangun untuk mendukung migrasi tanpa downtime.

Jelajahi V2

V1 didukung hingga Jan 2028. Rencanakan migrasi Anda hari ini.