تضمين الكائنات المرتبطة

اعرض القوائم دون طلب ثانٍ.

النمط

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

مثال: قائمة التلاوات

GET /recitations/ تُعيد عناصر مع أربعة موارد مرتبطة مدمجة:

{
  "count": 38,
  "results": [
    {
      "id": 7,
      "name": "حفص عن عاصم",
      "description": "تلاوة كاملة برواية حفص.",
      "publisher": { "id": 3, "name": "إتقان" },
      "reciter": { "id": 12, "name": "مشاري راشد العفاسي" },
      "riwayah": { "id": 1, "name": "حفص" },
      "qiraah": { "id": 2, "name": "عاصم", "bio": "أحد القراء السبعة المعتمدين." },
      "surahs_count": 114
    }
  ]
}

الحقل	الشكل	ملاحظات
publisher	{id, name}	موجود دائماً
reciter	{id, name}	موجود دائماً
riwayah	{id, name} أو null	فارغ عند عدم الانطباق
qiraah	{id, name, bio} أو null	يتضمن حقل عرض إضافياً واحداً

جميع قيم name مُحلَّلة عبر Accept-Language.

عقد ثابت

هذا الشكل ثابت. الموارد المرتبطة المدمجة المستقبلية تتبع نفس النمط: id أولاً، name ثانياً، حقل عرض إضافي اختياري واحد كحد أقصى. الـ API لا يُدمج كائناً متداخلاً كاملاً — العمق يبقى على مستوى واحد.

النمط المضاد: لا تتجنب المورد الكامل

إذا احتجت بيانات تتجاوز id وname — مثلاً، السيرة الذاتية الكاملة للقارئ أو بلده — استدعِ نقطة نهاية المورد الخاصة:

curl https://staging.api.cms.itqan.dev/reciters/12/

دمج السجلات الكاملة سيجعل استجابات القوائم كبيرة بشكل غير محدود. id في المضمَّن هو المؤشر الثابت للاستخدام عند الحاجة إلى المزيد.

---

انظر أيضاً: مبادئ التصميم · التوطين · التلاوات وتوقيتات الآيات