الإصدارات والإهمال
تسري هذه السياسة على API التكامل بأكملها: REST API v1، والأداة (widget)، وwebhook الصادرة والواردة، وSCIM 2.0. أما الاستدعاءات الداخلية التي تستخدمها بوابات Core وWorkspace وDesk فلا تشملها هذه السياسة، وقد تتغير في أي وقت: لا تستخدموها في التكاملات.
الإصدارات الرئيسية
Section titled “الإصدارات الرئيسية”- يرد الإصدار الرئيسي في المسار:
/api/v1/…. تتضمن كل استجابة من/api/v1الترويسةX-Exo-API-Version: 1. - الإصدار v1 مستقر. داخل v1 لا نجري إلا تعديلات متوافقة:
- نقاط نهاية جديدة، وحقول اختيارية جديدة في الطلبات، ومعاملات استعلام جديدة؛
- حقول جديدة في الاستجابات: يجب أن يتجاهل العميل الخاص بكم الحقول التي لا يعرفها؛
- أنواع جديدة من أحداث webhook: يجب أن يتجاهل نظامكم الأنواع التي لا يعرفها؛
- رموز أخطاء جديدة: عالجوا الرموز غير المعروفة بناءً على حالة HTTP؛
- ترويسات اختيارية جديدة.
- يتطلب التعديل غير المتوافق إصدارًا رئيسيًا جديدًا (
/api/v2). ويُعدّ غير متوافق: إزالة حقل أو نقطة نهاية أو حدث أو إعادة تسميته، أو تغيير نوع، أو جعل حقل اختياري إلزاميًا، أو تغيير المصادقة. - عند صدور إصدار رئيسي جديد، يبقى الإصدار السابق متاحًا لمدة 12 شهرًا على الأقل.
الإهمال
Section titled “الإهمال”- تستمر الوظيفة المُهمَلة في العمل لمدة 6 أشهر على الأقل من تاريخ الإعلان.
- تتضمن الاستجابات التي تستخدم وظيفة مُهمَلة ما يلي:
Deprecation: @<unix-seconds>: تاريخ الإعلان عن الإهمال (RFC 9745)؛Sunset: <HTTP-date>: تاريخ توقف الوظيفة عن العمل (RFC 8594)؛Link: <url>; rel="deprecation": دليل الانتقال.
- يرد كل إهمال في سجل التغييرات ويُعلَّم بـ
deprecatedفي مواصفة OpenAPI.
حالات الإهمال الجارية
Section titled “حالات الإهمال الجارية”| الوظيفة | تاريخ الإعلان | تتوقف عن العمل | البديل |
|---|---|---|---|
مفاتيح API nh_… |
1 نوفمبر 2026 | 30 يونيو 2027 | المفاتيح nhk.<keyid>.<secret> |
التوقيع X-NH-Signature في webhook الصادرة |
1 نوفمبر 2026 | 30 يونيو 2027 | X-Exo-Signature مع X-Exo-Timestamp |
التوقيع X-NH-Connector-Signature في webhook الواردة |
1 نوفمبر 2026 | 30 يونيو 2027 | X-Exo-Signature مع X-Exo-Timestamp |
الحقول event وtimestamp وsource في متن webhook |
1 نوفمبر 2026 | 30 يونيو 2027 | type، created_at، data |
المواصفة وسجل التغييرات
Section titled “المواصفة وسجل التغييرات”- مواصفة OpenAPI هي العقد. يتبع إصدارها نظام الإصدار الدلالي (semantic versioning)
1.MINOR.PATCH: يزداد MINOR مع الإضافات المتوافقة، ويزداد PATCH مع تصحيحات التوثيق فقط. - يؤدي كل تعديل على الـ API إلى تحديث إصدار المواصفة وإضافة بند إلى سجل التغييرات.