لماذا تصميم واجهة API (API) يستمر لفترة أطول من الكود نفسه
عندما يستهلك أحد ما واجهة API الخاصة بك، يصبح شكلها مجمدًا بشكل فعال. يمكنك إعادة كتابة كل شيء خلفها؛ لكنك لا تستطيع تغيير اسم حقل ما بشكل عشوائي يعتمد عليه تطبيق جوال موجود بالفعل، لأن إصدارات التطبيقات القديمة تبقى على هواتف الناس لسنوات.
هذا التفاوت هو السبب وراء ضرورة أن يكون العمل على واجهة API مبنيًا على التصميم أولاً. قضاء أسبوع في الاتفاق على العقد قبل التنفيذ يوفر الكثير لاحقًا، لأن البديل هو إصدار إصدارات جديدة للخروج من قرارات متخذة في فترة بعد الظهر.
العملية التي تعمل
1. جرد المستهلكين
من يستدعي هذه الواجهة، وما هي احتياجاتهم الفعلية؟ واجهة ويب أمامية، تطبيق جوال، تكامل مع شريك، ولوحة تحكم داخلية لها متطلبات مختلفة تمامًا. يهتم عملاء الهاتف المحمول بحجم Payload وعدد الجولات (round trips) بطريقة لا يهتم بها عميل الويب على النطاق العريض.
2. العقد أولاً
اكتب المواصفات — OpenAPI للـ REST، أو مخططًا لـ GraphQL — واتفق عليها قبل التنفيذ. هذا يوفر فائدتين فوريتيتن: يمكن أن يتابع فريق الواجهة الأمامية والخلفية العمل بشكل متوازٍ ضد نسخة وهمية، وتظهر الخلافات أثناء مراجعة الوثيقة بدلاً من اختبار التكامل.
3. نمذجة الموارد
يجب أن تعكس نقاط النهاية (endpoints) مجال عملك، وليس جداول قاعدة البيانات. إن التعرض لهيكل الجداول مباشرة يكون مريحًا في البداية ويصبح سجنًا: كل تغيير في المخطط يصبح تغييرًا مزعزعًا لواجهة API.
4. المصادقة والترخيص
قرر مبكرًا، لأن التعديل لاحقًا مؤلم:
- مفاتيح API للوصول بين الخوادم والشركاء
- OAuth 2.0 / OIDC حيث يمنح المستخدمون الوصول إلى بياناتهم الخاصة
- JWTs قصيرة الأجل مع رموز التحديث للتطبيقات التابعة لنا
واحتفظ بالترخيص منفصلاً عن المصادقة. معرفة من هو الشخص لا تخبرك بأي السجلات يمكنه رؤيتها، ودمج الاثنين هو مصدر شائع لثغرات تسرب البيانات.
5. الأخطاء، الترقيم، إصدار الإصدارات
الأجزاء غير الجذابة التي تحدد ما إذا كانت واجهة API سهلة الاستخدام أم لا:
- شكل الأخطاء المتسق مع رمز قابل للقراءة آليًا ورسالة بشرية
- الترقيم باستخدام المؤشرات (cursor pagination) بدلاً من الإزاحة (offset)، بحيث تظل النتائج ثابتة أثناء تغير البيانات
- إصدار الإصدارات من اليوم الأول —
/v1/لا يكلف شيئًا الآن ويوفر هجرة لاحقة - تحديد معدل الاستخدام مع رؤوس واضحة، حتى يتمكن المستهلكون من التراجع بدلاً من قطع الاتصال بشكل صامت
6. الوثائق كمنتج تسليم
مرجع مولد بالإضافة إلى أمثلة عملية، بما في ذلك كيفية المصادقة وما تعني الأخطاء الشائعة. إذا لم يتمكن مطور كفء من إجراء مكالمة ناجحة خلال عشرين دقيقة من قراءتها، فالوثائق لم تنتهِ بعد.
REST أم GraphQL
REST لمعظم المشاريع. يعمل التخزين المؤقت عبر HTTP، وسهولة التصحيح واضحة، وكل مطور يعرفه بالفعل، والأدوات شائعة.
GraphQL عندما يكون لديك عدة عملاء مختلفين يريدون أشكالًا مختلفة من نفس البيانات، أو عندما يكون الإفراط في الاسترجاع (over-fetching) على اتصالات الهاتف المحمول تكلفة قابلة للقياس. فهو يجلب تعقيدًا حقيقيًا — التخزين المؤقت، تحديد تكلفة الاستعلام، الحماية من الاستعلامات المتداخلة بعمق — يجب إدارتها بنشاط.
اختيار GraphQL لعملاء ويب واحد عادةً ما يكون تعقيدًا دون عائد. اختيار REST عندما يكون لديك أربعة عملاء يطلبون مجموعات مختلفة من البيانات يعني إما العديد من نقاط النهاية أو الكثير من البيانات الضائعة.
التكلفة الفعلية في المملكة المتحدة
| النطاق | النطاق النموذجي |
|---|---|
| واجهة API مركزة، موارد قليلة، مصادقة | £6,000 – £15,000 |
| تكامل مع واجهة API موثقة تابعة لجهة خارجية | £2,500 – £6,000 |
| تكامل مع أنظمة قديمة أو غير موثقة | £10,000 – £30,000 |
| بوابة API، تحديد معدل الاستخدام، بوابة المطورين | £8,000 – £20,000 |
النمط值得 الملاحظة: تكلفة التكامل مدفوعة بالنظام الآخر، وليس بك. واجهة API حديثة موثقة تستغرق أسبوعًا. نظام قديم غير موثق مع بيانات غير متسقة وبيئة اختبار غير موجودة يمكن أن يستهلك شهرًا. ولهذا السبب نحدد نطاقها أولاً كاختبار زمني محدود بدلاً من تقديم سعر ثابت — السعر الثابت على نظام غير معروف هو تخمين يدفعه شخص ما في النهاية.
تكامل الأنظمة القديمة
معظم المشاريع الحقيقية ليست مشاريع خضراء (greenfield). فهي تتضمن شيئًا قديمًا لا يزال يدير الأعمال.
إذا كان للنظام واجهة برمجة تطبيقات (API)، فتوقع أن تكون غير متسقة وبطيئة، وأن تفرض حدودًا للطلبات بطرق غير موثقة. قم ببناء دفاعي: إعادة المحاولات مع تراجع أسي (exponential backoff)، وقواطع الدائرة (circuit breakers)، و طابور (queue) حتى لا يؤدي الاعتماد البطيء إلى إسقاط تطبيقك بالكامل.
إذا لم يكن للنظام واجهة برمجة تطبيقات (API)، فخيارات التكامل — بترتيب متزايد من المتانة — هي: تبادل ملفات مجدول (CSV أو XML عبر SFTP)، أو تكامل قاعدة بيانات للقراءة فقط حيث يسمح البائع بذلك، أو — في حالات محدودة — أتمتة العمليات الروبوتية (RPA) التي تتحكم في الواجهة. الخيار الأخير هش للغاية ويتعطل بمجرد تغيير البائع للشاشة. سننفذه إذا لم يكن هناك خيار آخر، مع توضيح ما ستقبله.
أضف دائمًا طبقة مكافحة الفساد (anti-corruption layer). ترجم نموذج النظام القديم إلى نموذجك عند الحدود بدلاً من السماح بغرائبه بالانتشار في قاعدة الكود الخاصة بك. هذا القرار الوحيد يحدد ما إذا كان استبدال النظام القديم لاحقًا سيكون مشروعًا أو محنة.
الأخطاء الشائعة
- تعريض جداول قاعدة البيانات ك endpoints — يربط واجهة API الخاصة بك بقاعدة البيانات بشكل دائم
- عدم وجود إصدار (versioning) — يصبح التغيير الأول المسبب لكسر الوظيفة حالة طوارئ
- إضافة المصادقة لاحقًا — يعني invariably إعادة كتابة كل نقطة نهاية (endpoint)
- عدم وجود حدود للطلبات (rate limiting) — مستهلك سيئ الكتابة يمكنه إسقاط الخدمة للجميع
- أخطاء غير متسقة — يكتب كل مستهلك معالجة مخصصة لكل نقطة نهاية
- توثيق مكتوب في النهاية — لذا يكون سيئًا أو غير موجود على الإطلاق
كيف يبدو التسليم الجيد
- مواصفات OpenAPI متفق عليها قبل بدء التنفيذ
- اختبارات آلية تغطي العقدة الموثقة
- المصادقة والترخيص كمخاوف منفصلة ومختبرة
- حدود للطلبات مع رؤوس معلوماتية (headers) توضيحية
- تسجيل هيكلي وتتبع للأخطاء
- توثيق مع أمثلة عملية
- بيئة اختبار مراقبة يمكن للمستهلكين تطويرها ضدها
الخطوات التالية
إذا كنت تخطط لتكامل والنظام في الطرف الآخر مجهول، فالخطوة الأولى المنطقية هي إجراء اختبار قصير مدفوع لتحديد ما هو ممكن فعليًا. عادة ما يكلف جزءًا بسيطًا من المشروع، وقد يكشف أحيانًا أن التكامل الذي تم تقديم عرضه لك لا يمكن بناؤه بالطريقة الموصوفة.
الأسئلة المتكررة
عادةً ما تتراوح تكلفة واجهة برمجة تطبيقات مركزة مع عدد قليل من الموارد والمصادقة بين 6,000 جنيهًا إسترلينيًا و15,000 جنيهًا إسترلينيًا. بينما تتراوح تكلفة دمجها مع نظام قديم أو طرف ثالث معقد بين 10,000 جنيهًا إسترلينيًا و30,000 جنيهًا إسترلينيًا، لأن معظم التكلفة تكمن في النظام الآخر وليس في نظامك. قد تصل تكلفة دمج تكامل واحد مع طرف ثالث موثق جيدًا إلى 2,500 جنيهًا إسترلينيًا إلى 6,000 جنيهًا إسترلينيًا.
REST هو الخيار الأفضل في معظم الحالات: أسهل في التخزين المؤقت، وأسهل في التصحيح، وكل مطور يعرفه بالفعل. يستحق GraphQL تعقيده عندما يحتاج عملاء متعددون إلى أشكال مختلفة من نفس البيانات، أو عندما يجعل استهلاك النطاق الترددي للهاتف المحمول من زيادة البيانات مكلفًا حقًا. اختيار GraphQL لموقع ويب واحد فقط يضيف تعقيدًا دون عائد.
أربعة إلى ثمانية أسابيع لواجهة برمجة تطبيقات مركزة تشمل التوثيق والاختبارات. تعتمد عمليات التكامل بشكل شبه كامل على جودة النظام في الطرف الآخر — قد يستغرق واجهة برمجة تطبيقات حديثة وموثقة جيدًا أسبوعًا، بينما يستغرق النظام القديم غير الموثق وقتًا أطول بكثير، ويجب تحديد هذه الشكوك كاختبار استكشافي بدلاً من التخمين.
هناك عادةً خيارات بديلة: تبادل الملفات المجدول، أو تكامل على مستوى قاعدة البيانات (إن سمحت بذلك)، أو في حالات محدودة، أتمتة العمليات الروبوتية. جميعها أقل متانة من واجهة برمجة تطبيقات صحيحة، وسنخبرك بصراحة بالتسويات بدلاً من تقديم نهج هش على أنه مكافئ.
- API
- integration
- REST
- GraphQL
- architecture