دليل ترحيل واجهة برمجة التطبيقات - الترقية بين الإصدارات

خطط ونفذ ترقيات سلسة لإصدارات واجهة برمجة التطبيقات. فهم التغييرات غير المتوافقة، والجداول الزمنية للإيقاف، وأفضل الممارسات للترحيل بين إصدارات واجهة برمجة التطبيقات Smart Money.

نشر في 21 مارس 2026 16 دقيقة قراءة متقدم

نظرة عامة على الترحيل

يتم تطوير واجهة برمجة التطبيقات Smart Money بشكل نشط مع تحديثات منتظمة. يغطي هذا الدليل إدارة الإصدارات، والتغييرات غير المتوافقة، وكيفية ترحيل تكاملك دون توقف.

المبادئ الرئيسية للترحيل:

  • إصدار دلالي — تنسيق MAJOR.MINOR.PATCH يتبع بدقة
  • دعم طويل الأجل — الإصدار الرئيسي السابق مدعوم لمدة 24+ شهرًا
  • تحذيرات الإيقاف — إشعار مسبق لمدة 6 أشهر عن جميع التغييرات غير المتوافقة
  • إصدارات متوازية — تشغيل الإصدار 1 والإصدار 2 في نفس الوقت أثناء الترحيل
  • اختبار آلي — أدوات توافق مجموعة الاختبار متوفرة

الحالة الحالية: الإصدار 1 (الحالي)، الإصدار 2 (بيتا، متاح للعموم في الربع الثاني من 2026). الإصدار 1 مدعوم حتى الربع الأول من 2028.

سياسة إصدار النسخ

إصدار دلالي

تنسيق الإصدار
إصدار واجهة برمجة التطبيقات: MAJOR.MINOR.PATCH
مثال: 2.1.3
MAJOR (2) - تغييرات غير متوافقة، هندسة جديدة
MINOR (1) - ميزات متوافقة مع الإصدارات السابقة
PATCH (3) - إصلاحات أخطاء، تحديثات أمان

دورة إصدار النسخ

المرحلة المدة الخصائص
ألفا 2-4 أسابيع تغييرات غير متوافقة كثيرة، للاختبار فقط
بيتا 4-8 أسابيع مستقر إلى حد كبير، ملاحظات المجتمع
مرشح للإصدار 2-4 أسابيع جاهز للإنتاج، اللمسات النهائية
متاح للعموم 24+ شهرًا دعم إنتاج كامل
احصل على مفتاح واجهة برمجة التطبيقات في 30 ثانية

جاهز للبناء؟ احصل على مفتاح واجهة برمجة التطبيقات مجانًا (100 استدعاء/يوم، بدون بطاقة) وابدأ في سحب بيانات الحيتان الحية والتمويل والبيانات على السلسلة.

احصل على مفتاح واجهة برمجة التطبيقات →

التوافق مع الإصدارات السابقة

توافق الإصدارات

ضمن الإصدار الرئيسي، يمكنك دائمًا الترقية إلى إصدارات ثانوية أو إصلاحية بأمان:

  • عناوين نقاط النهاية — تبقى دون تغيير
  • الحقول المطلوبة — لا يتم إزالتها أبدًا (يتم إضافة حقول اختيارية جديدة فقط)
  • رموز حالة HTTP — محفوظة للسيناريوهات الحالية
  • هيكل الاستجابة — الحقول الأساسية تبقى كما هي
  • المصادقة — لا تغييرات في آليات المصادقة

إيقاف تدريجي

جدول زمني للإيقاف
// الشهر 1: إعلان الإيقاف
// الميزة معلمة برأس الإيقاف
إيقاف: version="2.2", sunset="2026-09-01"
// الشهر 3-6: فترة الإيقاف النشط
// واجهة برمجة التطبيقات تعطي تحذيرات ولكنها لا تزال تعمل
X-Deprecation-Warning: سيتم إزالة نقطة النهاية هذه في 2026-09-01
// الشهر 6: الإزالة النهائية
// نقطة النهاية تعطي 410 Gone
HTTP/1.1 410 Gone

الترحيل من الإصدار 1 إلى الإصدار 2

تغييرات رئيسية

  • إعادة تصميم واجهة برمجة التطبيقات REST — نقاط نهاية موارد أكثر نظافة
  • تنسيق الاستجابة — تغليف متسق، تحسين معالجة الأخطاء
  • المصادقة — إضافة دعم OAuth 2.0 (مفاتيح واجهة برمجة التطبيقات لا تزال تعمل)
  • تحديد المعدل — تحسين الدقة والوضوح
  • الخطافات الشبكية — إعادة تصميم تنسيق الحدث والتوقيع

تعيين نقاط النهاية

نقطة النهاية 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 يناير 2028 /v2/whales/tracking
/v1/funding يناير 2026 يناير 2028 /v2/derivatives/funding-heatmap
مصادقة بمفتاح API فقط مارس 2026 مارس 2027 OAuth 2.0 (المفاتيح لا تزال تعمل)
تنسيق Webhook v1 الربع الثاني 2026 الربع الثاني 2027 تنسيق 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"

تغييرات حقول الاستجابة

  • fundingfunding_rate
  • pricemark_price
  • volvolume_quote

الانتقال خطوة بخطوة

المرحلة 1: التخطيط (الأسبوع 1-2)

  1. مراجعة التكامل الحالي للميزات المهملة
  2. ربط نقاط نهاية V1 بنظيراتها في V2
  3. تحديد التغييرات الجوهرية التي تؤثر على الكود الخاص بك
  4. تخطيط استراتيجية الاختبار والجدول الزمني

المرحلة 2: التطوير (الأسبوع 3-4)

  1. إنشاء فرع V2 في التحكم بالإصدار
  2. تحديث جميع نقاط نهاية API إلى عناوين URL V2
  3. تحديث معالجة الطلب/الاستجابة
  4. تشغيل اختبارات الوحدة على الساندبوكس

المرحلة 3: الاختبار (الأسبوع 5-6)

  1. تشغيل مجموعة اختبار التكامل الكاملة
  2. اختبار سيناريوهات الأخطاء والحالات الحدية
  3. اختبار الحمل مع نقاط نهاية V2
  4. مراجعة أمنية للكود المحدث

المرحلة 4: المرحلة الانتقالية (الأسبوع 7)

  1. نشر كود V2 في بيئة الانتقال
  2. تشغيل اختبارات القبول الكاملة
  3. الحصول على موافقة أصحاب المصلحة
  4. إعداد خطة التراجع

المرحلة 5: الإنتاج (الأسبوع 8)

  1. نشر أزرق-أخضر في الإنتاج
  2. مراقبة المقاييس ومعدلات الأخطاء
  3. البقاء على أهبة الاستعداد لقضايا الدعم
  4. إيقاف تشغيل كود V1 تدريجيًا

الدعم والموارد

الأدوات المتاحة

  • مدقق الهجرة — فحص الكود للاستخدام المهمل
  • مدقق ترقية API — مقارنة توافق V1 و V2
  • قائمة مراجعة الهجرة — ملف PDF بالمهام والجدول الزمني
  • أمثلة الكود — عينات قبل/بعد الهجرة

الحصول على المساعدة

  • البريد الإلكتروني: [email protected]
  • التوثيق: انظر changelog-versioning.html
  • Discord: قناة دعم المجتمع
  • الشركات: مهندس هجرة مخصص

ابدأ هجرتك اليوم

قم بالترقية إلى API V2 مع أدوات هجرة شاملة، توثيق، ودعم. مصممة لدعم الهجرة دون توقف.

استكشف V2
سيتم دعم V1 حتى يناير 2028. خطط لهجرتك اليوم.

موارد ذات صلة

ابدأ مجانًا — 100 استدعاء/يوم، بدون بطاقة

احصل على تدفق الحيتان، التمويل، الفائدة المفتوحة وبيانات On-chain عبر 3 بورصات من API واحد. طبقة مجانية، بدون بطاقة ائتمان، ترقِ في أي وقت.

ابدأ مجانًا →
جرب وحدة تحكم API المباشرة → (لا حاجة لحساب)