ماذا يجب أن تتحقق منه عند تقييم تعريف API؟
تعريف API: ما هو
تعريف API هو العقد الموثق الذي يوضح كيفية استدعاء العميل لواجهة برمجة التطبيقات وكيف ستستجيب الواجهة. يتضمن عادةً مسارات نقاط النهاية، وصيغ طلب/استجابة (على سبيل المثال، حقول JSON)، وأنواع البيانات، والمعلمات المطلوبة مقابل الاختيارية، والمصادقة والصلاحيات، وحدود المعدل، وصيغ الأخطاء، وأي توقعات مذكورة بخصوص التوقيت أو الترتيب.
في سياق التداول الآلي، يهم تعريف API لأن كل خطوة لاحقة—إدخال البيانات، ومنطق الإشارات، وقرارات التنفيذ، والتقارير—تعتمد على ما تضمنه الواجهة مقابل ما “تحاول” فقط تقديمه. الهدف الرئيسي للتقييم هو فهم أي أجزاء هي آليات ثابتة وأي أجزاء يمكن أن تتغير مع ظروف السوق، وحمل النظام، وسياسات الموفر.
كيفية التحقق من تعريف API (قائمة تحقق موضوعية)
- اكتمال العقد (afvinkpunten)
- يتم سرد نقاط النهاية والطرق بشكل صريح.
- يتم تعريف مخططات الطلب والاستجابة، بما في ذلك معاني الحقول وأنواع البيانات.
- توجد أمثلة للاستجابات الطبيعية ولكل نوع خطأ موثق.
- تُذكر متطلبات المصادقة والتفويض (على سبيل المثال، كيف يتم تزويد بيانات الاعتماد وما هي الصلاحيات المسموح بها).
- تفاصيل السلوك (جزء “كيف يعمل”)
- تأكد مما إذا كانت الواجهة تحدد ترتيبًا أو اتساقًا عبر الاستدعاءات (على سبيل المثال، ما إذا كانت “الأحدث” مرتبطة بطابع زمني).
- راجع كيفية تمثيل الطوابع الزمنية (الصيغة والمنطقة الزمنية وما إذا كانت تعكس وقت الحدث أم وقت المعالجة).
- تحقق من كيفية عمل الترقيم (pagination) والتصفية والحدود، بما في ذلك الأحجام القصوى للصفحات والقيم الافتراضية.
- الشروط المتغيرة مقابل الآليات الثابتة
- افصل العناصر الثابتة (المخطط وقواعد المعلمات وأكواد الأخطاء الموثقة) عن العناصر المتغيرة (التأخر، فجوات البيانات، حركة السوق، والتقييد بسبب الحمل).
- تعامل أي تصريح حول “الوقت الحقيقي” أو “البث” باعتباره ادعاءً سلوكيًا يجب التحقق منه عبر الاختبارات أو أمثلة الاستجابات، وليس كوعـد ثابت.
- الأدلة وإثبات التوثيق ابحث عن مخرجات تنفيذية تتيح لك التحقق من العقد:
- توثيق يتضمن حمولة (payload) نموذجية واستجابات أخطاء.
- سياسة إدارة الإصدارات التي تصف كيف يتم إدخال التغييرات ولمدة بقاء الإصدارات القديمة مدعومة.
- موارد اختبار مثل بيئات sandbox أو نقاط نهاية وهمية (mock) أو استدعاءات أمثلة مسجلة.
- عبارات قيود واضحة (rode vlaggen) حدّد الفجوات حيث يكون التوثيق صامتًا أو غامضًا:
- تعريفات ناقصة لحقول حرجة.
- دلالات أخطاء غير واضحة (على سبيل المثال، ما إذا كان الخطأ قابلاً لإعادة المحاولة).
- لا يوجد وصف للـ backpressure أو سلوك تحديد المعدل، أو ما الذي يحدث أثناء الأعطال الجزئية.
دليل أو مثال: ماذا يعني “التحقق”
مثال عملي على التقييم المعتمد على الأدلة هو تشغيل استدعاءات برمجية تغطي:
- طلب “المسار السعيد” (happy path) والتحقق من أن حقول الاستجابة تطابق المخطط الموثق.
- على الأقل حالة حدية واحدة، مثل معلمة غير صالحة يجب أن تؤدي إلى خطأ موثق.
- فحص التأخر/التوقيت عبر قياس زمن الرحلة ذهابًا وإيابًا (round-trip time) ومقارنته بأي توقعات توقيت مذكورة.
مثال افتراض (اذكره صراحة): إذا قست زمن الاستجابة من ساعة نظامك أنت، فأنت تفترض أن ساعتك متزامنة بشكل معقول. وبدون هذا الافتراض، قد تكون مقارنات التوقيت مضللة.
القيود وأنماط الفشل التي يجب أخذها في الاعتبار
على الأقل، قيّم نمط فشل جوهريًا واحدًا:
- فجوات البيانات: قد تُرجع الواجهة تاريخًا غير مكتمل، أو أحداثًا مفقودة، أو تحديثات متأخرة.
- مشكلات التأخر والترتيب: حتى إذا كانت الطوابع الزمنية موجودة، فقد لا يطابق ترتيب الاستدعاءات ترتيب الأحداث.
- تحديد المعدل أو التقييد (throttling): قد تؤدي الطلبات المفرطة إلى تأخيرات أو أخطاء مُهيكلة.
- انحراف المخطط (Schema drift): قد تتغير إصدارات الواجهة من حيث الحقول أو الأنواع أو المعلمات المطلوبة.
- فشل المصادقة/الصلاحيات: قد تنتهي صلاحية الرموز أو قد تختلف نطاقات الوصول حسب البيئة.
العلاقات التاريخية لا تُثبت النتائج المستقبلية. حتى إذا بدت الاستجابات النموذجية متسقة، فقد تتغير السلوكيات المستقبلية عندما يقوم الموفر بتحديث الخدمات أو عندما يتغير حمل النظام وتقلبات السوق. كما تختلف النتائج مع التكاليف وطريقة التنفيذ والاختصاص القضائي، لذا تعامل تعريف API باعتباره وصفًا للعقد وليس ضمانًا للأداء.
معايير التحقق والأسئلة التالية
استخدم معيارًا واضحًا “klaarcriterium” (معايير الإنجاز) قبل التكامل:
- يمكنك ربط كل معلمة مطلوبة وكل حقل يتم إرجاعه بمعنى موثق.
- يمكنك إعادة إنتاج استجابات النجاح والأخطاء الموثقة في بيئة اختبار.
- لديك افتراضات موثقة بخصوص التوقيت وإعادة المحاولة واكتمال البيانات.
- لديك خطة للتعامل مع حدود المعدل والحقول غير المعروفة وتغيرات الإصدارات.
الأسئلة التالية التي يجب طرحها أثناء التقييم:
- ما هو نموذج الاتساق الموثق للواجهة بالضبط للطوابع الزمنية والترتيب؟ - ما الأخطاء القابلة لإعادة المحاولة، وما إرشادات backoff المقدمة؟