الخلاصة

  • يعرّف RFC 9727 المسار /.well-known/api-catalog وعلاقة الرابط api-catalog كي يعلن الناشر مجموعة من واجهات API. ولا يشهد بملكية كل عنصر أو صلاحية استعماله أو إمكان الوصول إليه أو مراقبته أو سلامته.
  • للفهرس الجذري والفهرس الموجود على نطاق آخر والفهارس المتداخلة سلطات نشر وسياقات وذاكرات مؤقتة ومواعيد تحديث مختلفة. البنية رسم بياني لادعاءات مؤرخة، لا سلسلة ثقة تُورَّث تلقائياً.
  • حذف item يثبت أن المنشور تغيّر. أما الإخراج الآمن من الخدمة فيحتاج إلى أدلة مستقلة عن التعرّض والحركة والاعتماديات والتنفيذ والتراجع والمراقبة اللاحقة.

ما يختفي من القائمة قد يبقى على الشبكة

نُشر RFC 9727 في فبراير 2025 على مسار المعايير في IETF. آليته صغيرة عمداً: يجيب الناشر عند /.well-known/api-catalog، ويمكنه الإعلان عن الفهرس بترويسة Link، ويقدمه بصيغة Linkset JSON. تسرد علاقة item واجهات API، بينما تصل علاقة api-catalog إلى فهارس فرعية.

تعالج هذه الآلية مشكلة حقيقية. فكثيراً ما تتوزع معرفة الواجهات بين إعدادات النشر والبوابات وبوابات المطورين وجداول خاصة. نقطة اكتشاف موحدة تحول الذاكرة المتناثرة إلى تصريح تقرؤه الآلات. لكنها لا تحوّل التصريح إلى نسخة كاملة من الأنظمة العاملة.

يعبّر RFC 8288 عن علاقات ذات نوع، لا عن شهادات تشغيل. وجود item صحيح نحوياً لا يثبت أن DNS يحل الاسم من شبكة محددة، أو أن منفذاً يستمع، أو أن الناشر يملك الهدف، أو أن اعتماداً مقبول، أو أن معاملة عمل تنجح. وكذلك لا يختفي مستمع غير مدرج.

يضع OWASP API9:2023 النسخ القديمة والمضيفين غير الموثقين والبيئات غير الواضحة ضمن مخاطر سطح الهجوم. يستطيع RFC 9727 تقليص العمى إذا قورن الفهرس بالبنية المعروضة. أما عدّ الروابط وحده فينتج يقيناً زائفاً أكثر ترتيباً.

لكل حافة في الرسم سلطة مستقلة

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

يسمح RFC 9727 بالإشارة إلى فهرس على نطاق آخر عندما يتعذر استضافة مورد well-known. عندها تصبح استجابة الاكتشاف وسلسلة إعادة التوجيه وهويات TLS والأزمنة وبصمة المحتوى أجزاء من سلسلة النشر. لا يكفي بقاء العنوان نفسه لإثبات استمرار السلطة.

تضاعف الفهارس المتداخلة هذه الحدود. قد يقود فهرس مؤسسة إلى منتجات، ثم إلى فهارس إقليمية لكل منها فريق ودورة إصدار وحد وصول. يطلب RFC 9264 سياقاً صريحاً لأن نقل Linkset من دون anchor قد يغير معناه. ليست البنية شجرة ترث الحقيقة؛ إنها مجموعة حواف مؤرخة.

يُفترض أن يحفظ إيصال الفهرس النطاق والمسار وإعادة التوجيه ونظير TLS ووقت الاستجابة ونوع الوسائط وprofile وETag أو Last-Modified وبصمة المتن وكل ثلاثية سياق–هدف–علاقة. أول مشاهدة وآخر مشاهدة ليستا تلقائياً تاريخ إنشاء وحذف. هذا اقتراح تحليلي، لا شرط إضافي في RFC.

ساعة الذاكرة المؤقتة ليست ساعة الخدمة

يميّز RFC 9111 بين الحداثة وإعادة التحقق واستخدام الاستجابة القديمة. يثبت ETag ثبات التمثيل بين عمليتي تحقق، ولا يثبت استمرار كل API في العمل. مدة حداثة طويلة قد تؤخر ظهور حذف عاجل، والمدة القصيرة تزيد الحمل ولا تصلح مصدراً مهملاً.

يجب فصل وقت قصد الناشر، ووقت رد المصدر، ووقت تحقق الذاكرة المؤقتة أو إعادة استخدامها، ووقت تغيير البوابة، ووقت المراقب. عبارة «لم تكن مدرجة عند الثانية» قابلة للفحص مع الاستجابة ومسار التخزين؛ لكنها لا تعني «توقفت عند الثانية».

يوصي RFC 9727 بمراقبة توافر الفهرس وأدائه، وربط قراءته بطلبات API اللاحقة، وإزالة العناصر القديمة، وفحص الصياغة وقواعد العمل، وإدخال التحديث في دورة الإصدار. ويقول بوضوح إن الفهرس يكمل إطار إدارة API ولا يستبدله.

سلامة الفهرس لا تعني سلامة العناصر

قد تنجح أداة في تحميل الفهرس والتحقق من JSON وعبور كل الفروع بينما يفشل item. وقد يفشل أصل الفهرس فيما يواصل عميل يعرف العنوان معاملاته. تشير علاقة status في RFC 8631 إلى مورد حالة، لكنها لا تدمج صفحة الحالة والفهرس وAPI في قياس واحد. اتصال TCP واستجابة HTTP ومعاملة موثقة ثلاث ملاحظات مختلفة.

يحذر RFC 9727 أيضاً من كشف الواجهات الداخلية. تحمي TLS والمراجعة وأقل صلاحية كتابة وتحديد المعدل والتحكم في الوصول عملية النشر؛ ولا تثبت أن هدفاً داخلياً غير متاح من الخارج. والقدرة على قراءة الفهرس لا تمنح حق استخدام عناصره.

حذف البطاقة ليس إغلاقاً للمقبس

قد يكشف تدقيق الفهرس واجهات API «زومبي» بلا دعم أو مراقبة أو تصحيح. وهي خطرة لأن السجل الإداري انفصل عن النظام الجاري. الاكتشاف يبدأ التحقيق ولا يصدر شهادة إيقاف.

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

ينبغي لإيصال الإخراج أن يربط آخر لقطة وقراراً مخولاً بتغييرات DNS والتوجيه وموازن الحمل والبوابة؛ وبالواجهات والبيئات؛ وبالمالكين والمهام التابعة؛ وبحركة لها نافذة قياس ونقاط عمياء؛ وبالاعتمادات ومسارات البيانات؛ وبإقرار التنفيذ؛ وبمسؤول الاستثناء والتراجع؛ وبالاختبارات اللاحقة. مهمة فصلية أو شبكة شريك خارج القياس تبقى «مجهولة»، لا صفراً.

تغطي مقالة BTW القائمة عن Deprecation وSunset حدود هجرة العميل. أما هنا فالمسألة أضيق: حذف علاقة من الفهرس ليس دليلاً على التنفيذ. قد يظل الخادم يجيب بعد الحذف، أو يختفي قبل إزالة الرابط. يجب الاحتفاظ بالتعارض بوصفه دليلاً.

المصادر

المواصفات والسجلات: RFC 9727، سجل RFC Editor، IETF Datatracker، سجل IANA لمسارات well-known، سجل IANA لعلاقات الروابط، RFC 9264، RFC 8288، RFC 8615، RFC 8631، RFC 9111، RFC 9745، RFC 8594، OWASP API9:2023.

إطار تحليلي منسوب: Lu Heng، الملاحظة 64، أولوية الشفرة العاملة، لماذا تسجل BTW الواقع.