كل كابوس تكامل استُدعيت لإصلاحه يبدأ بالطريقة نفسها: أحدهم بنى المنتج أولاً، ثم فكّر في الـ API لاحقاً. فتسرّب مخطط قاعدة البيانات إلى نقاط النهاية (endpoints)، وحصل فريق الموبايل على كتلة JSON «مؤقتة» عمّرت أطول من ثلاثة مدراء تنفيذيين. وحين طلب أحد الشركاء أخيراً وصولاً برمجياً، كانت الإجابة الصادقة: «أمهلونا ثلاثة أشهر».
يقلب تصميم الواجهات أولاً (API-First) هذا الترتيب رأساً على عقب. فأنت تعامل الواجهة بوصفها أول ما يُسلَّم في المنتج: تُصمَّم وتُراجَع ويُتَّفَق عليها قبل كتابة سطر واحد من منطق العمل. قد يبدو الأمر عبئاً إجرائياً إضافياً، لكنه عملياً أرخص تأمين يمكنك شراؤه ضد ديون التكامل التي تخنق معظم الأنظمة بصمت بحلول عامها الثالث.
ما الذي يعنيه «API-first» فعلاً (وما لا يعنيه)
هو لا يعني «لدينا نقاط نهاية REST»، فهذا يملكه الجميع تقريباً. تصميم الواجهات أولاً يعني أن العقد (contract) يسبق الكود: تكتب مخطط OpenAPI أو GraphQL، وتنشره، وتترك المستهلكين — الموبايل والويب والشركاء وخدماتك المستقبلية — يتجادلون حوله بينما التغيير ما زال مجانياً. وعندئذ فقط يبدأ أحدهم بالبناء.
يهمّ هذا التمييز بسبب توقيت وصول الملاحظات. ففي بيئة «الكود أولاً» يكون الـ API ناتجاً عرضياً لما أفرزه الـ ORM، فتكتشف خطأ التصميم يوم يحاول عميلٌ استخدامه فعلاً — وهي أغلى لحظة ممكنة للاكتشاف. أما تصميم الواجهات أولاً فيقدّم هذا الاكتشاف إلى الأمام، حيث لا تتجاوز كلفةُ إعادة تسمية حقلٍ تعليقاً على طلب دمج (pull request) بدل دورة إيقاف كاملة.
العقد هو المنتج. أما التنفيذ فمجرد الطريقة الراهنة التي تفي بها بهذا العقد.
لماذا يؤتي ثماره — وأين يكمن العائد فعلاً
المكسب الأوضح هو التوازي. فبمجرد تجميد العقد، يعمل فريق الواجهة الأمامية والخلفية والشركاء معاً على خادم وهمي (mock server) في آنٍ واحد بدل الاصطفاف خلف بعضهم. وفي مشاريعي، كثيراً ما ضغط هذا وحده بناءً متسلسلاً يستغرق شهرين إلى خمسة أو ستة أسابيع متوازية.
أما المكاسب الأقل وضوحاً فتتراكم بأثر أقوى:
- قابلية المحاكاة. خادم وهمي مبني على المخطط (Prism أو WireMock أو MSW) يتيح لفريقَي الجودة والتصميم البدء من اليوم الأول، مقابل استجابات واقعية، قبل وجود الواجهة الخلفية.
- توليد كل شيء. ملف OpenAPI واحد يولّد حِزم SDK للعملاء، وهياكل الخادم، والنماذج المُنمَّطة، والتوثيق. ولا سبيل لأن ينحرف التوثيق عن الواقع لأنه مبني من المصدر نفسه.
- اختبارات العقد. أدوات مثل Pact تلتقط أي تغيير كاسر في مرحلة التكامل المستمر (CI)، لا في قناة حوادث أحد الشركاء عند الثانية فجراً.
- حرية الخيارات. أعِد كتابة الخدمة بلغة Go، أو قسّمها إلى ثلاث، أو انقلها خلف طابور رسائل — لن يلاحظ المستهلكون شيئاً، لأنهم لم يرتبطوا يوماً إلا بالعقد.
كيف تطبّقه فعلاً يوم الاثنين
لست بحاجة إلى فريق منصّات ولا إلى سنةٍ من التمويل، بل إلى انضباطٍ يتّبع ترتيباً محدداً.
1. صمّم العقد في العلن
اكتب المواصفة كملف قابل للمراجعة داخل المستودع — OpenAPI 3.1 لواجهات REST، أو SDL لـ GraphQL. وعامِل طلبات الدمج عليه معاملة القرارات المعمارية، لأنها كذلك فعلاً. وأشرِك في المراجعة المستهلكين الحقيقيين، لا الفريق المالك للخدمة وحده.
2. نمذِج الموارد، لا صفوف قاعدة البيانات
واجهتك لغةُ مجالٍ (domain language)، لا مُفرَغ SQL. سمِّ الأشياء كما يتحدث بها العمل: الفواتير، الشحنات، الاشتراكات — لا tbl_inv_2. وإن كانت نقطة النهاية لا تُفهَم إلا بعد أن يشرح أحدهم بنية جداولك، فأعِد تصميمها.
3. أصدِر النسخ وطوّرها بتعمّد
حدّد قواعد التوافق قبل الإطلاق: الإضافات مجانية، والحذف وإعادة التسمية تغييرات كاسرة، والتغييرات الكاسرة تنال نسخة جديدة مع نافذة إيقاف حقيقية. دوِّن ذلك، فالفرق التي تتجاوز هذه الخطوة تنتهي بها الحال إلى v1 وv1_new وv1_final في الإنتاج.
4. أتمِت حواجز الأمان
افحص المواصفة آلياً (Spectral)، وقارنها بالإصدار السابق لكشف التغييرات الكاسرة، وولّد منها العملاء ضمن الـ CI. فما إن تفرض الآلةُ العقدَ، حتى يكفّ «سنكون حذرين» عن كونه خطّ دفاعك الوحيد.
المفاضلات الصادقة
تصميم الواجهات أولاً ليس مجانياً، والتظاهر بعكس ذلك هو ما يقود إلى هجره. فالتصميم المسبق يبدو بطيئاً وأنت تحدّق في مخطط فارغ والعرض التوضيحي مضروبٌ ليوم الجمعة. أما النموذج الأولي الذي ستلقيه فعلاً، فتجاوز عنه — إذ يفوق طقسُه عائدَه. لكن ما إن يعتمد أكثر من فريق، أو طرفٌ خارجي واحد، على تلك الواجهة، حتى تنقلب المعادلة بشدّة. فتكلفة العقد السيئ لا تدفعها أنت، بل يدفعها كل من تكامل معه، مراراً، لسنوات.
والفخّ الآخر هو معاملة المواصفة كتوثيق تكتبه لاحقاً. فعقدٌ تولّده من كودٍ قيد التشغيل ليس «API-first»، بل هو «كود أولاً» بملفات PDF أجمل. وجوهر الفكرة أن يقع التصميم قبل أن يتمكن التنفيذ من التحيّز له.
من أين تبدأ
اختر خدمتك الجديدة القادمة — لا إعادة كتابة، بل خدمةً على أرضٍ بكر. وقبل أن يفتح أحدٌ محرره، اكتب ملف OpenAPI، وأقِم منه خادماً وهمياً، ودع الواجهة الأمامية ومستهلكاً واحداً في المصبّ يبنيان مقابله لأسبوع. ستلمس الفرق في أول دورة عمل (sprint): رسائل أقل من نوع «مهلاً، ماذا يعني هذا الحقل؟»، ولا فرق معطّلة، وواجهةٌ تُقرأ وكأنها صُمِّمت لا وكأنها أُفرزت.
وفي المرة القادمة التي تُغرى فيها بـ«توصيل نقاط النهاية وتوثيقها لاحقاً»، اسأل: من سيدفع ثمن هذا القرار — وهل ستكون أنت حقاً؟