واجهات جديدة دون تعطيل الربط القائم
يحدّث هذا العمل الواجهات التي تتحدث عبرها برمجياتك مع الأنظمة الأخرى. وقد يعني ذلك أن يحل تصميم متسق على REST أو GraphQL محل خدمات SOAP أو نقاط النهاية غير الموثقة، أو إضافة مصادقة سليمة وإدارة للإصدارات وحدود لمعدل الطلبات، أو وضع طبقة نظيفة فوق نظام قديم. ونخطط للتغيير حول الجهات التي تعتمد اليوم على ما هو قائم.
وهو يناسب الشركات التي يتعطل الربط لديها مع كل إصدار، أو يشكو شركاؤها من التوثيق، أو تتباطأ فرق الجوال والويب فيها بسبب واجهة صُممت لزمن آخر. ونطاقه أضيق من إعادة كتابة النظام كله. فكثيراً ما تبقى الأجزاء الداخلية كما هي في الوقت الحالي، ولا يُعاد بناء سوى العقد الذي يراه الآخرون.
حصر الواجهات
نسجّل كل نقطة نهاية، ومن يستدعيها، وكم مرة، وبأي حقول، معتمدين على سجلات الحركة إلى جانب التوثيق، لأنهما نادراً ما يتطابقان.
تصميم الواجهة
نحدد الموارد والتسميات والأخطاء وتقسيم النتائج إلى صفحات والتصفية بأسلوب متسق في مخطط OpenAPI أو GraphQL، ونراجعه مع الفرق التي ستستخدمه.
استراتيجية الإصدارات
نحدد طريقة ترقيم الإصدارات، ومدة دعم كل إصدار، وطريقة الإعلان عن التغييرات، فتستطيع الجهات المستخدمة أن تخطط، ولا يختفي شيء دون إنذار.
اختبار التوافق
نعيد تشغيل طلبات حقيقية مسجَّلة على التنفيذين القديم والجديد ونقارن الاستجابات، فتظهر فروق ما كان التوثيق ليكشفها أبداً.
الطبقة الوسيطة والبوابة
توجّه البوابة الحركة بين الخدمات القديمة والجديدة، وتحوّل الصيغ عند الحاجة، وتضيف المصادقة والحد من الطلبات والتسجيل في مكان واحد.
نقل الجهات المستخدمة
تحصل كل جهة على دليل للانتقال وبيئة تجريبية وجدول زمني، ونتابع استخدام الإصدار القديم حتى يمكن إيقافه بأمان.
ما تتسلمه منا
- حصر نقاط النهاية والجهات المستخدمة
- مواصفات واجهة البرمجة ودليل الأسلوب
- سياسة الإصدارات والإيقاف التدريجي
- تنفيذ واجهة البرمجة المحدَّثة
- حزمة اختبارات التوافق
- توجيه البوابة وسياساتها
- توثيق للمطورين وبيئة تجريبية
- أدلة انتقال للجهات المستخدمة
طريقة عملنا
- 01
الحصر والاستماع
نوثّق الموجود انطلاقاً من الشيفرة والحركة الفعلية، ونحدد كل جهة مستخدمة ونسألها عمّا يعيقها، وهذا يعيد عادةً ترتيب الأولويات التي افترضها مزوّد الواجهة.
- 02
تصميم العقد
نحدد مواصفات الواجهة الجديدة ونراجعها قبل كتابة الشيفرة، مع خوادم محاكاة تتيح للفرق المستخدمة تجربتها مبكراً وإثارة المشكلات ما دام تغييرها قليل التكلفة.
- 03
البناء بالتوازي
ننفّذ نقاط النهاية الجديدة خلف بوابة إلى جانب القائمة، وتؤكد اختبارات التوافق المبنية من الحركة المسجَّلة تطابق السلوك حيث يُفترض أن يبقى كما هو.
- 04
الانتقال والإيقاف
تنتقل الجهات المستخدمة بترتيب متفق عليه وبدعم منا، ونراقب الحركة على الإصدار القديم وهي تنخفض، ولا نوقف أي نقطة نهاية قديمة إلا حين يصل استخدامها إلى الصفر.
التقنيات التي نستخدمها
| المجال | التقنيات |
|---|---|
| التصميم | OpenAPI، GraphQL، AsyncAPI، Stoplight |
| بيئة التشغيل | Node.js، TypeScript، Python، Go |
| البوابات | Kong، AWS API Gateway، Apigee، Envoy |
| الاختبار | Pact، Postman، k6، Schemathesis |
واجهتك البرمجية تعيق كل من يستخدمها
تراكمت نقاط النهاية مع الوقت دون نمط مشترك، والتوثيق قديم، وقد يعطّل تغيير صغير ربطاً مع شريك دون إنذار. وتبني الفرق الداخلية حلولاً التفافية. وأنت تريد واجهة نظيفة موثقة، وطريقة آمنة لنقل كل الجهات المستخدمة إليها.
- خدمات SOAP ما زالت مستخدمة
- نقاط نهاية داخلية غير موثقة
- واجهات الشركاء والواجهات العامة
- خوادم تطبيقات الجوال تحت ضغط
- واجهات فوق أنظمة قديمة
- واجهات برمجة قبل إطلاق منصة
أسئلة شائعة
هل يمكن تحديث واجهة البرمجة دون تعطيل الربط القائم؟
نعم، بتشغيل القديم والجديد جنباً إلى جنب. تواصل الواجهة الحالية عملها بينما تُقدَّم الجديدة، وغالباً خلف البوابة نفسها. وتنتقل الجهات المستخدمة وفق جدول متفق عليه، ولا يوقَف الإصدار القديم إلا حين تُظهر الحركة أن أحداً لم يعد يستخدمه. وتؤكد اختبارات التوافق المبنية من طلبات حقيقية أن ما يُفترض أن يبقى كما هو قد بقي فعلاً.
هل نختار REST أم GraphQL للواجهة الجديدة؟
يناسب REST معظم عمليات الربط بين الأنظمة والواجهات العامة أو واجهات الشركاء، لأنه مفهوم على نطاق واسع ويسهل تخزينه مؤقتاً. أما GraphQL فيفيد حين تحتاج واجهات أمامية متنوعة إلى أشكال مختلفة من البيانات نفسها، وتكون الجهات المستخدمة تحت سيطرتك. وبعض المؤسسات تستخدم الاثنين. ونقرر بناءً على من سيستخدم الواجهة وكيف، ولا نعتمد أسلوباً لمجرد أنه جديد.
هل يجب أن نعيد كتابة النظام الذي يقف خلف الواجهة؟
ليس بالضرورة. فالطبقة الوسيطة تستطيع أن تقدّم واجهة حديثة وتترجم الاستدعاءات إلى النظام القديم تحتها. وهكذا تحصل الجهات المستخدمة على عقد مستقر فوراً، ويمكن استبدال الأجزاء الداخلية لاحقاً، قطعة بعد قطعة، دون جولة أخرى من تغييرات الربط. وحين لا يستطيع النظام القديم تلبية متطلبات الأداء أو الموثوقية، نقول ذلك صراحة ونخطط لاستبداله في مرحلة منفصلة.
كيف تتعاملون مع الإصدارات والإيقاف التدريجي؟
بسياسة مكتوبة تعتمد عليها الجهات المستخدمة. تحدد ما يُعدّ تغييراً يكسر التوافق، وكيف تُميَّز الإصدارات، وكم يبقى الإصدار القديم مدعوماً، وكيف يصل الإشعار. أما التغييرات التي تضيف دون أن تمس الموجود فتصدر دون إصدار جديد. ونقيس استخدام نقاط النهاية المقرر إيقافها، ونتواصل مباشرة مع المسؤولين عن الجهات المتبقية قبل إيقاف أي شيء.
ما الذي يجعل واجهة البرمجة مريحة للمطورين؟
الاتساق، والأخطاء الواضحة، والتوثيق الصادق. فينبغي أن تتكرر الأسماء والأنماط في كل نقاط النهاية، وأن تقول رسائل الخطأ ما الذي حدث وكيف يُصلَح، وأن يُولَّد المرجع من المواصفات نفسها التي تُبنى عليها الشيفرة فلا يبتعد عنها. وبيئة تجريبية ببيانات نموذجية وبضعة أمثلة عملية تفيد في الإقبال على الواجهة عادةً أكثر من أي قدر من الشرح.