مبادئ التصميم

تشرح هذه الصفحة قرارات التصميم خلف Itqan CMS API. فهم هذه المبادئ يساعدك على بناء تكاملات صحيحة وقابلة للصيانة وجاهزة للتوسع المستقبلي.

REST و JSON

تتبع جميع واجهات الاستدعاء البرمجية اتفاقيات REST. الموارد عبارة عن أسماء جمع في مسارات URL متوقعة (/reciters/، /recitations/، /riwayahs/). كل جسم استجابة هو JSON مع Content-Type: application/json. تحمل أفعال HTTP معناها المعتاد: GET للقراءة، POST للإنشاء، وهكذا.

معرّفات موارد ثابتة

لكل مورد حقل id صحيح. هذه المعرّفات ثابتة: بمجرد تعيينها، سيشير معرّف القارئ 42 دائماً إلى ذلك القارئ. يمكنك حفظ المعرّفات في قاعدة بياناتك، وتضمينها في URLs، والإشارة إليها عبر الطلبات دون القلق من تغييرها عبر إصدارات الـ API.

غلاف الاستجابة

تُلفّ واجهات الاستدعاء البرمجية للقوائم المُصفَّحة حمولتها في غلاف متسق:

{
  "count": 150,
  "results": [...]
}

count هو إجمالي عدد السجلات المطابقة (ليس فقط الصفحة الحالية). results يحتوي على صفحة العناصر. واجهات الاستدعاء البرمجية للمورد الواحد تُعيد الكائن مباشرة — بدون غلاف.

راجع هيكل الاستجابة للتفاصيل الكاملة.

الموارد المرتبطة المدمجة

عندما يشير مورد إلى آخر (تلاوة تشير إلى ناشرها وقارئها وروايتها وقراءتها)، يُدمج الـ API كائناً مضغوطاً {id, name} مباشرة بدلاً من URL أو مفتاح خارجي صحيح فارغ. يتيح لك هذا عرض عنصر قائمة كامل — الاسم، الأسماء المرتبطة، الأعداد — من طلب واحد.

{
  "id": 7,
  "name": "حفص عن عاصم",
  "publisher": { "id": 3, "name": "إتقان" },
  "reciter": { "id": 12, "name": "مشاري راشد العفاسي" },
  "riwayah": { "id": 1, "name": "حفص" }
}

عندما تحتاج السجل الكامل لمورد مرتبط، استدعِ نقطة نهايته الخاصة باستخدام id المدمج.

راجع تضمين الكائنات المرتبطة لمواصفة النمط الكاملة.

الحقول المدركة للغة

الحقول التي تحمل نصاً قابلاً للقراءة — name، description، bio — تُعيد المحتوى باللغة المطلوبة عبر ترويسة Accept-Language. أرسل Accept-Language: ar للعربية، Accept-Language: en للإنجليزية. مفتاح JSON دائماً نفسه (name، ليس name_ar أو name_en)؛ القيمة فقط تتغير.

راجع التوطين لاستخدام الترويسة وتغطية الحقول.

غلاف خطأ موحّد

جميع الاستجابات غير 2xx تشترك في نفس البنية:

{
  "error_name": "not_found",
  "message": "No asset matches the given query.",
  "extra": null
}

error_name معرّف ثابت يمكن قراءته آلياً — قم بتحويل معالجة الأخطاء بناءً عليه، ليس على message أو حالة HTTP. message وصف قابل للقراءة البشرية، مُحلَّل عبر Accept-Language — آمن للعرض مباشرة للمستخدمين. extra يحمل تفاصيل منظمة اختيارية (مثلاً، أخطاء التحقق على مستوى الحقل).

راجع معالجة الأخطاء للكتالوج الكامل للأخطاء.

التطور المتوافق مع الإصدارات السابقة

يتطور الـ API بشكل إضافي. قد تظهر حقول جديدة في الاستجابات الموجودة في أي وقت؛ يجب أن يتجاهل عميلك الحقول غير المعروفة بدلاً من الفشل بسببها. التغييرات المخلّة — الحقول المُزالة، الأنواع المُغيَّرة، نقاط النهاية المُعاد تسميتها — تُقدَّم دائماً على قطعة مسار جديدة. التكامل المبني على /recitations/ اليوم سيستمر في العمل مع إضافة حقول جديدة.

---

انظر أيضاً: هيكل الاستجابة · تضمين الكائنات المرتبطة · معالجة الأخطاء