إدارة الإصدارات

يُحدَّد إصدار Partner API في عنوان URL. والإصدار الحالي هو:

https://partner-api.performancehub.co/partner/v1/

سياسة التغيير

يسعى Performance Hub إلى إجراء تغييرات إضافية ومتوافقة مع الإصدارات السابقة كلما أمكن ذلك.

أمثلة على التغييرات المتوافقة مع الإصدارات السابقة:

إضافة حقل اختياري جديد إلى الطلب.
إضافة حقل جديد إلى الاستجابة.
إضافة نقطة نهاية جديدة.
إضافة قيمة تعداد جديدة حيث يُتوقع من العملاء التعامل مع القيم غير المعروفة.
تحسين رسائل التحقق دون تغيير عقد رموز الحالة.

access_time_windows وaccess_time_windows_revision حقلان إضافيان في طلب العضو. والعملاء الحاليون الذين يحذفونهما يُبقون لقطة Access Time Window المخزنة دون تغيير. وتحافظ قاعدة الحذف هذه على التوافق مع الإدراج أو التحديث الجزئي؛ فالحذف لا يعادل إرسال مصفوفة فارغة.

أمثلة على التغييرات الجذرية:

إزالة حقل أو إعادة تسميته.
تغيير نوع حقل.
جعل حقل طلب اختياري مطلوبًا.
إزالة نقطة نهاية.
تغيير معنى رمز حالة موجود أو reason خاص بمجال معين.

الإهمال

عندما يلزم إجراء تغيير جذري، يتجنب Performance Hub تغيير الإصدار الحالي في مكانه كلما أمكن ذلك. وبدلًا من ذلك، سنطرح إصدارًا جديدًا أو مسار ترحيل ونبلغ الشركاء المتأثرين بالتغيير.

يمكن أن تتضمن إشعارات الإهمال ما يلي:

إدخالًا في سجل التغييرات.
تواصلًا مباشرًا مع الشركاء.
ملاحظات في Partner Console.
إرشادات الترحيل في الوثائق.

توصيات للعملاء

أنشئ عملاء يتحملون التغييرات الإضافية:

تجاهل حقول الاستجابة التي لا تستخدمها.
تعامل مع قيم التعداد غير المعروفة على أنها غير مدعومة بدلًا من التسبب في تعطل التطبيق.
تجنّب فحوصات التطابق الصارم للاستجابات.
سجّل القيم غير المعروفة حتى تتمكن من تحديث تكاملك عن قصد.

بالنسبة إلى أقسام العضو ذات المراجعات مثل Access Time Windows، احتفظ بالمراجعة المرسلة والحمولة الموحّدة حتى تُعرف النتيجة. وإعادة استخدام مراجعة لمحتوى متغيّر تُعدّ تعارضًا، بينما إعادة إرسال المحتوى نفسه آمنة من التكرار. راجع Access Time Windows.

مواصفات OpenAPI

استخدم مواصفات OpenAPI المنشورة لإنشاء العملاء، والتحقق من الطلبات، وتتبع تغييرات بنية API بمرور الوقت.

راجع مواصفات OpenAPI.