概要バージョン管理ポリシー後方互換性 V1からV2への移行エンドポイント変更点レスポンスフォーマットの更新廃止予定スケジュール破壊的変更ステップバイステップ移行ガイドサポート & リソース

APIドキュメント

API移行ガイド — バージョン間のアップグレード

APIバージョンアップを円滑に計画・実行するためのガイド。破壊的変更、廃止予定スケジュール、Smart Money APIバージョン間移行のベストプラクティスを解説。

公開日: 2026年3月21日 • 読了時間16分 • 上級者向け

移行概要

Smart Money APIは定期的に更新される活発な開発プロジェクトです。本ガイドでは、ダウンタイムゼロで統合を移行する方法、バージョン管理、破壊的変更について説明します。

移行の基本原則:

セマンティックバージョニング — MAJOR.MINOR.PATCH形式を厳密に遵守
長期サポート — 以前のメジャーバージョンを24ヶ月以上サポート
廃止予告 — 破壊的変更の6ヶ月前通知を義務化
並行バージョン運用 — 移行期間中はv1とv2を同時に運用可能
自動テスト — 互換性テストスイートを提供

現在の状況: v1(現行バージョン)、v2(ベータ、2026年Q2一般提供予定)。v1は2028年Q1までサポート。

バージョン管理ポリシー

セマンティックバージョニング

バージョン形式
APIバージョン: MAJOR.MINOR.PATCH
例: 2.1.3
MAJOR (2) - 破壊的変更、新アーキテクチャ
MINOR (1) - 後方互換性のある新機能
PATCH (3) - バグ修正、セキュリティ更新

バージョンリリースサイクル

段階	期間	特徴
アルファ	2-4週間	破壊的変更が多い、テスト専用
ベータ	4-8週間	ほぼ安定、コミュニティフィードバック募集
リリース候補	2-4週間	本番環境準備完了、最終調整
一般提供	24ヶ月以上	完全な本番サポート

30秒でAPIキーを取得

開発準備はできましたか？無料APIキー(200コール/日、カード不要)を取得して、ライブの鯨情報、資金調達データ、オンチェーンデータを取得しましょう。

APIキーを取得 →

後方互換性

バージョン互換性

メジャーバージョン内では、常に新しいマイナー/パッチバージョンに安全にアップグレード可能:

エンドポイントURL — 変更なし
必須フィールド — 削除されない(新しいオプションフィールドのみ追加)
HTTPステータスコード — 既存シナリオで維持
レスポンス構造 — コアフィールドは同一保持
認証 — 認証メカニズムに変更なし

段階的廃止

廃止予定スケジュール
// 1ヶ月目: 廃止予告
// Deprecationヘッダーでマーク
Deprecation: version="2.2", sunset="2026-09-01"
// 3-6ヶ月目: 廃止進行期間
// APIは警告を返すが機能は継続
X-Deprecation-Warning: このエンドポイントは2026-09-01に削除されます
// 6ヶ月目: 完全削除
// エンドポイントは410 Goneを返す
HTTP/1.1 410 Gone

V1からV2への移行

主な変更点

REST API再設計 — より整理されたリソースエンドポイント
レスポンスフォーマット — 一貫したラッピング、改善されたエラー処理
認証 — OAuth 2.0サポート追加(APIキーも継続利用可能)
レート制限 — 改善された粒度と明確化
Webhook — 再設計されたイベントフォーマットと署名

エンドポイントマッピング

v1エンドポイント	v2エンドポイント	変更点
GET /whales	GET /v2/whales/tracking	再編成、フィルタリング機能追加
GET /funding	GET /v2/derivatives/funding-heatmap	取引所パラメータ必須化
GET /positions	GET /v2/derivatives/positions	新集計オプション追加

エンドポイント変更点

リクエストパラメータ変更

V1リクエスト
// V1: 資金調達レート
GET /v1/funding?symbol=BTCUSDT&exchange=binance

V2リクエスト
// V2: 同一データ、より明確な構造
GET /v2/derivatives/funding-heatmap?
  symbol=BTCUSDT&
  exchange=binance

レスポンスフォーマットの更新

V1 レスポンス構造

V1 フォーマット
{
 "status": "success",
 "data": {
 "symbol": "BTCUSDT",
 "funding": 0.0001
  }
}

V2 レスポンス構造

V2 フォーマット
{
 "data": {
 "symbol": "BTCUSDT",
 "funding_rate": 0.0001
  },
 "_meta": {
 "request_id": "req_abc123",
 "timestamp": 1709980800000
  }
}

主な違い: ステータスラッパーなし、フィールド名が明確化、メタデータが標準化。

非推奨タイムライン

計画された非推奨

機能	発表日	サンセット日	代替
/v1/whales	2026年1月	2028年1月	/v2/whales/tracking
/v1/funding	2026年1月	2028年1月	/v2/derivatives/funding-heatmap
APIキーのみの認証	2026年3月	2027年3月	OAuth 2.0（キーは引き続き有効）
Webhook v1フォーマット	2026年第2四半期	2027年第2四半期	Webhook v2フォーマット

破壊的変更の詳細

削除されたエンドポイント

/v1/stats — /v2/metricsに置き換え
/v1/historical — 新しいパラメータで/v2/historicalに置き換え
/v1/alerts/create — POST /v2/alertsに置き換え

パラメータの変更

limit — デフォルトが100から20に変更（明示的に指定してください！）
timeframe — 履歴クエリで必須に
sort — フォーマットが"field asc"から"field:asc"に変更

レスポンスフィールドの変更

funding → funding_rate
price → mark_price
vol → volume_quote

ステップバイステップの移行

フェーズ1: 計画（第1-2週）

非推奨機能の既存統合を監査
v1エンドポイントをv2相当にマッピング
コードに影響する破壊的変更を特定
テスト戦略とタイムラインを計画

フェーズ2: 開発（第3-4週）

バージョン管理でv2ブランチを作成
すべてのAPIエンドポイントをv2 URLに更新
リクエスト/レスポンス処理を更新
サンドボックスに対してユニットテストを実行

フェーズ3: テスト（第5-6週）

完全な統合テストスイートを実行
エラーシナリオとエッジケースをテスト
v2エンドポイントでの負荷テスト
更新されたコードのセキュリティ監査

フェーズ4: ステージング（第7週）

v2コードをステージング環境にデプロイ
完全な受け入れテストを実行
ステークホルダーから承認を得る
ロールバック計画を準備

フェーズ5: 本番（第8週）

ブルーグリーンデプロイで本番環境に展開
メトリクスとエラーレートを監視
サポート問題に対応するためにオンコール
v1コードを段階的に廃止

サポートとリソース

利用可能なツール

移行バリデーター — 非推奨の使用をコードでチェック
APIアップグレードチェッカー — v1とv2の互換性を比較
移行チェックリスト — タスクとタイムラインのPDF
コード例 — 移行前後のサンプル

ヘルプの入手

メール: [email protected]
ドキュメント: changelog-versioning.htmlを参照
Discord: コミュニティサポートチャンネル
エンタープライズ: 専任の移行エンジニア

今日から移行を開始

包括的な移行ツール、ドキュメント、サポートでAPI v2にアップグレード。ゼロダウンタイム移行をサポート。

V2を探索

V1は2028年1月までサポート。今日から移行を計画してください。