APIإصدارات RTC
الـ /v1 الوعد
Section titled “الـ /v1 الوعد”كل ما يندرج تحت /v1 التغييرات بشكل إضافي فقط. قد تضيف RTC:
- مسارات جديدة، وحقول الطلب الاختيارية، ومعلمات الاستعلام؛
- حقول استجابة جديدة، ورموز الأخطاء، وأنواع أحداث webhook، وقيم التعداد؛
- رؤوس استجابة جديدة.
قم بإنشاء عملاء يتجاهلون الحقول غير المعروفة ويعاملون رمز الخطأ غير المعروف كأنه الرمز العام لحالة HTTP الخاصة به. لا تقوم RTC بإزالة أي حقل أو إعادة تسميته، أو تغيير نوعه أو معناه، أو جعل الإدخال الاختياري إلزاميًا، أو إعادة استخدام رمز خطأ تحت /v1.
يتم إصدار التغييرات الجذرية كمسار رئيسي جديد، /v2. ثم يعمل كلا الإصدارين جنبًا بجانب لفترة 12 شهرًا على الأقل قبل /v1 تم إيقافه، مع إشعار على هذا الموقع.
تثبيت أشكال الاستجابات باستخدام RTC-Version
Section titled “تثبيت أشكال الاستجابات باستخدام RTC-Version”تؤدي بعض التحسينات إلى تغيير شكل الإجابة دون تغيير معناها، مثل مغلف الأخطاء المنظم. وهي متاحة للاشتراك حسب الطلب مع رأس إصدار مؤرخ:
RTC-Version: 2026-11-01| الإصدار | التغييرات |
|---|---|
| لا شيء | الأشكال الأصلية. الأخطاء هي { "error": "<message>", "code"? }. |
2026-11-01 | تستخدم الأخطاء المغلف { "error": { code, message, details?, requestId, retryable, docUrl } }. |
تطبق RTC أحدث إصدار لا يتجاوز تاريخ إرسالك، وتقوم بتكراره في RTC-Version رأس الاستجابة. التاريخ الأقدم من الإصدار الأول يحافظ على الأشكال الأصلية. قم بتثبيت الإصدار الذي كُتب كودك بناءً عليه وقم بتغييره عمدًا عند الترقية.
تثبيت حمولات webhook باستخدام apiVersion
Section titled “تثبيت حمولات webhook باستخدام apiVersion”كل نقطة نهاية webhook يحتوي على apiVersion التي تعمل على تصحيح المغلف الذي تستلمه، بغض النظر عن رؤوس الطلبات:
apiVersion | المغلف |
|---|---|
legacy | { id, type, createdAt, projectId, data }، تم ترحيل الويب هوك الفردي السابق إلى نقطة نهاية |
2026-11-01 | { id, type, apiVersion, createdAt, tenantId, projectId, roomId?, data }، وهو الإعداد الافتراضي لنقاط النهاية الجديدة |
الحدث data تنمو بشكل تراكمي مثل API. لنقل مستقبل إلى إصدار أحدث من الحمولة، أضف نقطة نهاية ثانية بالإصدار الجديد، وقم بتبديل المعالجة، ثم قم بإزالة نقطة النهاية القديمة.
إصدار العقد لـ SDKs
Section titled “إصدار العقد لـ SDKs”GET /v1/capabilities التقارير contractVersion، والذي يتغير كلما أضيف شيء جديد إلى عقد العميل. SDKs يمكن استخدامه لتمكين الميزات الأحدث فقط في الحالات التي تدعمها API بالفعل.
وصف OpenAPI
Section titled “وصف OpenAPI”يتم وصف مسارات العملاء في RTC في OpenAPI 3.1، الذي تم إنشاؤه من المخططات التي APIتتحقق من صحة الطلبات بها ويتم مقارنتها بالكود عند كل تغيير. الملف موجود في docs/openapi/v1.yaml في مستودع منصة RTC . اتصل بنا CHAMPREP إلى تلقي الملف الحالي لتوليد العميل؛ هذا المرجع و
API مرجع تظل الوثائق العامة كما هي.