البحث والتصفية والترتيب

ثلاثة قوالب استعلام تتحكم فيما تحصل عليه وبأي ترتيب. يمكن دمج الثلاثة في طلب واحد.

البحث (search=)

بحث نصي حر عبر الاسم والوصف وأسماء الموارد المرتبطة (بالعربية والإنجليزية). المطابقة لا تراعي حالة الأحرف وتبحث عن السجلات التي تحتوي على المصطلح.

curl "https://staging.api.cms.itqan.dev/recitations/?search=مشاري"

على /recitations/، يُطابق المعامل search مع:

• name
• description
• publisher.name
• reciter.name (عربي وإنجليزي)
• riwayah.name (عربي وإنجليزي)
• qiraah.name (عربي وإنجليزي)

الكلمات المتعددة تُطابَق بمنطق AND — search=حفص+عاصم يُعيد السجلات التي تطابق كلاً من "حفص" و"عاصم".

التصفية

تُظهر نقاط النهاية معاملات تصفية خاصة بكل مورد. جميعها تقبل قيماً متعددة (OR منطقي).

التلاوات (/recitations/)

المعامل	النوع	الوصف
publisher_id	صحيح (قابل للتكرار)	تصفية حسب معرّف الناشر
reciter_id	صحيح (قابل للتكرار)	تصفية حسب معرّف القارئ
riwayah_id	صحيح (قابل للتكرار)	تصفية حسب معرّف الرواية
qiraah_id	صحيح (قابل للتكرار)	تصفية حسب معرّف القراءة

مرر المعامل عدة مرات لمطابقة أي من القيم (منطق OR):

# تلاوات القارئ 12 أو القارئ 15
curl "https://staging.api.cms.itqan.dev/recitations/?reciter_id=12&reciter_id=15"

الترتيب (ordering=)

رتّب النتائج حسب حقل واحد أو أكثر. أضف - قبل اسم الحقل للترتيب التنازلي. افصل الحقول المتعددة بفاصلة.

التلاوات (/recitations/)

الحقول المسموح بها: name، created_at، updated_at

# أبجدياً حسب الاسم (تصاعدي)
curl "https://staging.api.cms.itqan.dev/recitations/?ordering=name"

# الأحدث تحديثاً أولاً
curl "https://staging.api.cms.itqan.dev/recitations/?ordering=-updated_at"

القراء (/reciters/) والروايات (/riwayahs/)

الحقل المسموح به: name

curl "https://staging.api.cms.itqan.dev/reciters/?ordering=-name"

دمج الثلاثة

curl "https://staging.api.cms.itqan.dev/recitations/\
?search=حفص\
&publisher_id=3\
&reciter_id=12\
&ordering=-created_at\
&page=1\
&page_size=20"

يُعيد هذا تلاوات تطابق "حفص"، نشرها الناشر 3، للقارئ 12، مرتبة بالأحدث أولاً، الصفحة 1.

Python

import urllib.request, urllib.parse, json

params = urllib.parse.urlencode({
    "search": "حفص",
    "publisher_id": 3,
    "reciter_id": 12,
    "ordering": "-created_at",
    "page": 1,
    "page_size": 20,
})
url = f"https://staging.api.cms.itqan.dev/recitations/?{params}"

with urllib.request.urlopen(url) as resp:
    data = json.load(resp)

print(f"{data['count']} تلاوات مطابقة")
for r in data["results"]:
    print(f"  [{r['id']}] {r['name']}")

JavaScript

const params = new URLSearchParams({
  search: "حفص",
  publisher_id: 3,
  reciter_id: 12,
  ordering: "-created_at",
  page: 1,
  page_size: 20,
});
const resp = await fetch(`https://staging.api.cms.itqan.dev/recitations/?${params}`);
const { count, results } = await resp.json();

console.log(`${count} تلاوات مطابقة`);
results.forEach(r => console.log(`  [${r.id}] ${r.name}`));

---

انظر أيضاً: التصفيح · تضمين الكائنات المرتبطة · مرجع الـ API