دورة حياة واجهة Naasher API

تستخدم واجهة Naasher API إصدارًا رئيسيًا ظاهرًا في المسار: كل العمليات العامة الحالية تبدأ من https://api.naasher.com/api/sdk/v1. يظل الإصدار الرئيسي ثابتًا ما دامت التغييرات متوافقة مع العملاء القائمين.

ما الذي يمكن أن يتغير داخل v1؟

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

أي تغيير غير متوافق ينتقل إلى إصدار رئيسي جديد، مثل /api/sdk/v2، ويعمل الإصداران بالتوازي خلال فترة الانتقال.

كيف نعلن الإهمال التدريجي؟

عندما تصبح عملية أو نسخة قديمة:

1. يوسم عقد OpenAPI العملية بـ deprecated: true ويشير إلى البديل.
2. تعيد العملية ترويسة Deprecation ورابط Link إلى هذه السياسة أو دليل الترحيل.
3. عند اعتماد تاريخ الإيقاف، تعيد أيضًا ترويسة Sunset بتاريخ HTTP واضح.
4. يبقى المسار متاحًا مدة لا تقل عن 180 يومًا من أول إعلان قبل الإزالة.

لا توجد عملية عامة في v1 موسومة بالإهمال التدريجي وقت آخر تحديث لهذه الصفحة.

استثناءات الأمان

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

ما الذي يجب على العميل مراقبته؟

• عقد OpenAPI 3.1 وحقل deprecated.
• ترويسات Deprecation وSunset وLink في كل استجابة.
• سجل تغييرات ناشر قبل ترقية التكاملات الإنتاجية.
• الرموز الآلية الثابتة في نموذج الخطأ؛ لا تبنِ المنطق على نص الرسالة وحده.