سير عمل إيقاف واجهة برمجية (API) وإصدارها القديم بأمان — من إعلان الإهمال (Deprecation) وجدول الإيقاف، إلى نسخنة الإصدار ومسار الترحيل ومراقبة الاستخدام المتناقص، حتى الإيقاف النهائي (Sunset) والإزالة

سير عمل تنفيذي (runbook) يدير إيقاف واجهة برمجية (API) أو مسار أو إصدار قديم تُقدّمه أنت لعملائك، من قرار الإهمال حتى الإزالة النهائية، دون كسر العملاء المعتمدين عليه. الهدف تحويل «سأحذف هذا الـ endpoint القديم» من مخاطرة تكسر تكاملات العملاء فجأة، إلى عملية معلنة ومقيسة: تُعلن الإهمال بمهلة كافية، وتوفّر بديلًا ومسار ترحيل، وترسل إشارات تقنية واضحة، وتراقب الاستخدام حتى يتناقص، ثم توقف وتزيل بأمان. المبدأ الحاكم: الواجهة العامة عقدٌ مع الغير؛ لا يُنقض العقد بصمت، بل يُنهى بإعلان ومهلة وبديل. يختلف هذا السير جوهريًا عن أصول قريبة في السوق ولا يكرّرها. أولًا هو ليس «سير عمل ترقية التبعيات الآمنة (Dependency Upgrade)»؛ ذاك يعالج الطرف المُستهلِك — أنت ترقّي مكتبة تعتمد عليها وتقرأ سجل تغييراتها وتثبّتها في ملف القفل — بينما هذا السير يعالج الطرف المُقدِّم: أنت صاحب الواجهة التي يعتمد عليها آخرون، وتديـر تقاعدها وإبلاغهم وترحيلهم. هما وجهان متقابلان للعقد لا تكرار. وثانيًا هو ليس «سير النشر بإطلاق تدريجي (Canary)»؛ ذاك يوجّه حصة من حركة الإنتاج إلى بناء جديد ويحكم على صحته خلال دقائق/ساعات، بينما هذا يدير انسحاب سطح واجهة عبر أسابيع أو أشهر مع تواصل مع العملاء ومراقبة تناقص الاستخدام. وثالثًا هو ليس «سير ترحيل قاعدة البيانات بدون توقف (توسيع ثم انكماش)»؛ ذاك يغيّر مخطط تخزين داخلي، بينما هذا يتقاعد عقدًا خارجيًا مرئيًا للعملاء. ورابعًا هو ليس «سير دورة حياة أعلام الميزات (Feature Flags)»؛ ذاك مفتاح تشغيل زمن-تشغيل يُفعّل أو يُطفئ سلوكًا، بينما هذا يزيل واجهة منشورة بجدول معلن وإشارات وترحيل. وخامسًا هو ليس مجرد «كتابة إشعار إهمال»؛ الإشعار خطوة واحدة ضمن سبع مراحل تشمل النسخنة والمراقبة والإيقاف التدريجي والإزالة. يميّز السير أنواع الإيقاف لأن مخاطرها ومسارها يختلفان: إيقاف مسار/endpoint واحد، أو إيقاف إصدار كامل من الواجهة (v1 كله)، أو إيقاف حقل/معامل ضمن استجابة قائمة، أو إيقاف واجهة عامة (خارجية) مقابل داخلية. الواجهة العامة الخارجية تحتاج نافذة أطول وتواصلًا أوسع وربما سياسة نسخنة معلنة (Versioning/Deprecation Policy)، بينما الواجهة الداخلية بين خدماتك قد تُنهى أسرع لأنك تعرف كل مستهلكيها. لا يُعامَل حذف حقل صغير كإيقاف إصدار كامل، ولا يُوقَف عقد خارجي بنفس سرعة عقد داخلي. يعمل السير عبر سبع مراحل: (1) الجرد وقرار الإهمال: حدّد الواجهة/المسار/الإصدار وسبب إيقافه (إعادة تصميم، دمج، تكلفة صيانة، مخاطرة أمنية، استبدال بأفضل)، ومن يستهلكه فعليًا — استخرج المستهلكين من سجلات الوصول ومفاتيح API وأنماط الاستخدام، لأن ما لا تعرف مستهلكيه لا تستطيع إيقافه بأمان. (2) الإعلان وجدول الإيقاف: أعلن الإهمال رسميًا، وحدّد تاريخ Sunset بنافذة كافية تتناسب مع حجم العملاء وحرجيّة الواجهة، وبلّغ عبر التوثيق وسجل التغييرات والبريد لأصحاب المفاتيح ولوحة الحالة. (3) النسخنة ومسار الترحيل: وفّر البديل (الإصدار/المسار الجديد) ودليل ترحيل يربط القديم بالجديد حقلًا بحقل، وطبقة توافق مؤقتة إن أمكن — لا تعلن إزالة بلا بديل جاهز. (4) الإشارات التقنية: أضِف ترويسات الاستجابة القياسية Deprecation وSunset ورابط دليل الترحيل عبر ترويسة Link، وتحذير Warning، وفق RFC 8594، بحيث يكتشف العملاء الإهمال آليًا من الاستجابة نفسها لا من نشرة بريدية فقط. (5) مراقبة الاستخدام المتناقص: تتبّع عدد النداءات للواجهة المُهمَلة لكل عميل عبر الزمن، ولاحِق العملاء المتأخرين بالتواصل، ولا تُوقِف ما زال عليه حِمل معتبَر من عملاء لم يُرحّلوا. (6) الإيقاف التدريجي (Brownout) ثم فرض الإيقاف: قبل الإزالة النهائية نفّذ انقطاعات قصيرة مجدولة (Brownouts) تكشف العملاء الخفيّين الذين لم يلحظوا الإشعارات، ثم عند تاريخ Sunset افرض الإيقاف بردّ 410 Gone (أو إعادة توجيه للجديد حيث يناسب) لا 404 صامت يُربك التشخيص. (7) الإزالة والتنظيف: احذف المسار والكود والاختبارات القديمة، وألغِ المفاتيح والصلاحيات المرتبطة حصرًا بالواجهة المُوقَفة، وحدّث التوثيق وأرشِف، وراجِع من بقي يطرق الباب بعد الإيقاف. تحكمه قواعد صارمة: وفّر بديلًا ومسار ترحيل قبل إعلان الإزالة، ولا تُعلن سحبًا بلا وجهة بديلة. امنح نافذة إهمال كافية تتناسب مع حجم العملاء وحرجيّة الواجهة، ولا تُفاجئ العملاء بإيقاف عاجل إلا لضرورة أمنية قصوى معلّلة. بلّغ عبر عدة قنوات (ترويسات + توثيق + بريد + سجل تغييرات)، ولا Sunset صامت. استخدم الإشارات القياسية (ترويسات Deprecation وSunset وفق RFC 8594) و410 Gone بعد الإيقاف بدل 404 صامت. لا تُزِل واجهة ما زال عليها حِمل معتبَر من عملاء لم يُرحّلوا قبل انقضاء المهلة المعلنة والتواصل معهم. ميّز الواجهة العامة الخارجية عن الداخلية وعامل كلًّا بنافذته المناسبة. ولا تخترع أرقام استخدام أو أسماء عملاء أو تواريخ غير معلومة؛ اطلب المدخل الجوهري الناقص بدل التخمين. مناسب لمهندسي الـ Backend وفرق المنصّات (Platform) ومسؤولي الـ API وقادة الإصدار الذين يديرون واجهات REST أو GraphQL أو gRPC ويريدون تقاعد إصدار قديم أو مسار أو حقل دون كسر تكاملات العملاء، وقابل للتحويل إلى runbook أو checklist داخل الفريق ومع Claude Code وCursor وCodex.

خطة إيقاف واجهة برمجية عربية منظّمة وقابلة للتطبيق: بطاقة الإيقاف (الواجهة، نوعه، السبب، المستهلكون ومصدر معرفتهم)، خطة إعلان وجدول Sunset بنافذة مبرَّرة وقنوات إبلاغ متعددة، نسخنة ومسار ترحيل يربط القديم بالجديد مع طبقة توافق مؤقتة، إشارات تقنية بترويسات Deprecation وSunset وLink وWarning وفق RFC 8594 وسلوك 410 Gone بعد الإيقاف، خطة مراقبة للاستخدام المتناقص لكل عميل وعتبة السماح بالإيقاف، ثم جدول Brownout وخطوات الإزالة والتنظيف وإلغاء المفاتيح — كله مبني على توفير بديل قبل الإعلان، ونافذة كافية، وتبليغ متعدد القنوات، ودون إزالة صامتة أو مفاجئة قبل ترحيل العملاء وتناقص الحِمل، ودون اختراع أرقام استخدام أو أسماء عملاء أو تواريخ.