# استعمال الواجهة البرمجية (API Usage)

> نسبة الحسابات التي تستدعي الواجهة البرمجية بانتظام، وحجم الاستدعاءات لكل حساب مستعمِل.

- **المجال:** المنتج الرقمي (Product Management)
- **الوحدة:** %
- **تكرار القياس:** شهري
- **الاتجاه المرغوب:** أعلى أفضل
- **النوع:** تابع (Lagging)
- **الرابط:** https://kpihub.co/k/prod-api-usage

## الهدف

قياس المنتج كمنصّة لا كتطبيق، فالحساب الذي بنى شيئًا فوق واجهتك لن يتركه بسهولة.

## لماذا هو مهم

- الاستعمال البرمجي أعمق من التكامل الجاهز: العميل استثمر وقت مطوّريه
- يكشف احتياجات لا تظهر في الواجهة الرسومية، فهي خارطة منتج مجانية
- نموّ الاستدعاءات يتنبّأ بنموّ الحساب قبل أن يظهر في الإيراد

## المعادلة

```
API Usage % = (Accounts calling the interface regularly ÷ Active accounts) × 100
```

«بانتظام» يحتاج عتبة مكتوبة: استدعاء واحد شهريًّا ليس استعمالًا. وبلا عتبة يظهر كل من جرّب مرة كمستعمِل، فيبدو الرقم مرتفعًا بلا معنى.

## مثال محسوب

‏1,840 حسابًا نشطًا، يستدعي 294 الواجهة بانتظام بمتوسط 41,000 استدعاء شهريًّا. الحساب: (294 ÷ 1,840) × 100 = 16%، ويمثّلون 38% من الإيراد.

## النطاق الاسترشادي

لا معيار عام. المعيار العملي هو حصّتهم من الإيراد ومن التسرّب: مستعمِلو الواجهة عادةً أعلى إيرادًا وأقلّ تسرّبًا بفارق كبير.

## تحليل الاتجاه

- نموّ الاستدعاءات لحساب بعينه يتنبّأ بترقيته أو بحاجته لباقة أعلى
- ارتفاع نسبة الاستدعاءات الفاشلة يعني وثائق ناقصة أو واجهة متغيّرة
- تركّز الاستدعاءات في نقطة واحدة يعني حاجة تستحقّ ميزة في الواجهة الرسومية

## أسئلة تشخيصية

- ما نسبة الاستدعاءات الفاشلة؟ وما أسبابها؟ الوثائق أشيع سبب
- أي نقطة تُستدعى أكثر؟ الجواب حاجة تستحقّ ميزة رسومية
- هل مستعمِلو الواجهة أقلّ تسرّبًا؟ الفارق يبرّر الاستثمار فيها

## نصائح عملية

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

## العرض المناسب

- أعمدة بالنقطة لعدد الاستدعاءات
- خط زمني للاستدعاءات مع خط نسبة الفشل
- مقارنة التسرّب والإيراد: مستعمِلو الواجهة مقابل غيرهم

## تحذيرات وفخاخ

- بلا عتبة استعمال منتظم يظهر كل من جرّب مرة كمستعمِل
- تغيير الواجهة بلا مهلة إشعار يكسر تكاملات العملاء ويفقدهم
- قراءة عدد الاستدعاءات وحده يخفي أن حسابًا واحدًا يصنع أغلبها

## أثر التغيير

- رفع الاستعمال من 16% إلى 25% يوسّع الشريحة الأعلى إيرادًا والأقلّ تسرّبًا
- خفض الاستدعاءات الفاشلة بتحسين الوثائق يوفّر دعمًا ويسرّع التكامل
- تحويل النقطة الأكثر استدعاءً إلى ميزة رسومية يخدم شريحة أوسع بكثير

## احسبه في أداتك

### Excel

```excel
=COUNTIFS(A[MonthlyCalls],">="&Threshold) / COUNTA(A[AccountID])
```

### Power BI (DAX)

```dax
API Usage % =
DIVIDE (
    CALCULATE ( DISTINCTCOUNT ( 'Account'[AccountID] ), 'Account'[MonthlyApiCalls] >= [Threshold] ),
    DISTINCTCOUNT ( 'Account'[AccountID] )
)
```

### Tableau

```
COUNTD( IF [Monthly Calls] >= [Threshold] THEN [Account ID] END ) / COUNTD([Account ID])
```

### SQL

```sql
SELECT endpoint,
       COUNT(*)                                        AS calls,
       COUNT(*) FILTER (WHERE status_code >= 400) * 100.0
         / NULLIF(COUNT(*), 0)                         AS failure_pct,
       COUNT(DISTINCT account_id)                      AS accounts
FROM   api_call
WHERE  called_at BETWEEN :from_date AND :to_date
GROUP  BY endpoint
ORDER  BY calls DESC;
```

---

المصدر: [KPIHub](https://kpihub.co/k/prod-api-usage) · مرجع عربي مجاني لمؤشرات الأداء.