واجهة البرمجة العامة تستخدم المسار الأساسي /api/v1. كل عميل لازم يرسل Accept: application/json، ويقدر يحدد لغة الرسائل عبر Accept-Language: ar أو Accept-Language: en.
استجابة ناجحة
{
"success": true,
"data": {},
"message": "تمت العملية بنجاح",
"request_id": "00000000-0000-0000-0000-000000000000",
"meta": {}
}
حقل meta اختياري ويظهر عادةً مع القوائم المرقمة.
استجابة خطأ
{
"success": false,
"data": null,
"message": "تعذر تنفيذ الطلب",
"request_id": "00000000-0000-0000-0000-000000000000",
"errors": {},
"error_code": "REQUEST_ERROR"
}
حقلا errors وerror_code اختياريان حسب نوع الخطأ.
الترقيم
القوائم الكبيرة تستخدم أرقام الصفحات وحدًا أقصى للنتائج. بيانات الترقيم ترجع داخل meta، وقد تشمل الصفحة الحالية، آخر صفحة، وعدد العناصر الإجمالي.
المصادقة
بعض المسارات عامة، وبعضها يحتاج جلسة مستخدم صالحة. العميل ما يفترض أن إخفاء زر في الواجهة يمنح أو يمنع الصلاحية؛ الخادم هو جهة التحقق النهائية.
حدود الاستخدام
تُطبق حدود طلبات لحماية الخدمة ومنع إساءة الاستخدام. عند تجاوز الحد ترجع استجابة 429 مع رسالة واضحة، وعلى العميل الانتظار قبل المحاولة مرة ثانية.