API وسيط للـدرر السنية

عن المشروع

منذ مدة حاولت استعمال الـ API الخاص بالدرر السنية لكنني واجهت بعض الصعوبات منها أن الـ API يتعامل مع JSONP فقط وأيضًا لم أستطع أن أتعامل معه بالطرق العادية بسبب الـ CORS والـ JSONP وفي حالة مقدرتك على تجاوز هذه العقبات فتحصل على الناتج بهيئة HTML وأيضًا لا يوجد documentation أو مستند ما يشرح تفاصيل هذا الـ API وكيفية التعامل معه وأيضًا تشعر أنه قديم ولم يعد هناك اهتمام بصيانته أو تحسينه أو إضافة مميزات له فأنا قررت عمل API وسيط يتجنب مشكلة CORS ويعطيك البيانات كهيئة JSON وليس كـ HTML عن طريق عمل عمليات تنقية للـ HTML وتحويله لـ JSON بجانب شرح مفصل للـ API وكيفية استخدامه بالإضافة إلى احتوائه على بعض الخصائص الإضافية التي لا توجد في الـ API الرسمي عن طريق عمل scraping للموقع كله وليس فقط الـ API الخاص بهم القديم لأن الموقع يقدم مميزات وخواص أكثر بكثير من الـ API الرسمي الخاص بهم

أبرز ما يقدمه

أبرز ما يقدمه هذا الـ API الوسيط:

• يتجنب مشكلة CORS والتعامل مع الـ JSONP
• يعطيك البيانات كهيئة JSON بدلاً من HTML
• شرح مفصل للـ API وكيفية استخدامه (Swagger UI و Postman)
• خصائص إضافية غير موجودة في الـ API الرسمي

تنبيهات الاستخدام

بعض الملاحظات المهمة عند استخدام الـ API:

• يتم عمل cache لكل عملية بحث لمدة 5 ثواني
• هناك حد للاستخدام: 100 عملية بحث في اليوم لكل IP
• يمكنك تعديل هذه الإعدادات من ملف config.js

الـ Endpoints المتاحة

يحتوي الـ API على مجموعة من الـ endpoints للبحث والاستعلام:

• البحث عن الأحاديث عبر الـ API الرسمي للدرر (15 نتيجة) أو عبر صفحة البحث (30 نتيجة)
• جلب حديث معين أو أحاديث مشابهة أو الحديث الصحيح البديل عن طريق الـ id
• جلب أصول الحديث وطرق إخراجه مع جميع المصادر والأسانيد
• البحث عن شرح الأحاديث بالنص أو بالـ id
• جلب معلومات عن المحدثين والكتب
• جلب البيانات المرجعية: الكتب، الرواة، المحدثون، درجات الأحاديث، طرق ونطاقات البحث

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

يدعم الـ API مجموعة واسعة من خيارات التصفية:

• تحدد طريقة البحث: «جميع الكلمات» أو «أي كلمة» أو «بحث مطابق»
• استبعاد كلمة أو جملة من البحث
• تحديد نطاق البحث: جميع الأحاديث، المرفوعة، القدسية، آثار الصحابة، أو شروح الأحاديث
• تحديد درجة الحديث: صحيح أم ضعيف (حكم على المتن أو الإسناد)
• تحديد أسماء المحدثين (مثل البخاري، مسلم، الإمام مالك...)
• تحديد الكتب المراد البحث فيها (مثل صحيح البخاري، صحيح مسلم، الأربعون النووية...)
• تحديد أسماء الرواة (مثل أبو هريرة، ابن عباس، عمر بن الخطاب...)
• التحكم في عرض الأحاديث للمتخصصين أو لغير المتخصصين
• إزالة عناصر HTML من نتائج البحث
• وجود Pagination للتنقل بين صفحات النتائج مع 100 نتيجة لكل صفحة

التوثيق

يتوفر عدة طرق للاطلاع على توثيق الـ API:

• واجهة Swagger UI التفاعلية لاستكشاف واختبار جميع الـ endpoints من المتصفح
• Postman Collection جاهز مع أمثلة على جميع الطلبات
• شرح مفصل لكل endpoint مع جميع الخيارات المتاحة

تشغيل المشروع

خطوات بسيطة لتشغيل الـ API على جهازك:

• عمل fork أو clone للمشروع من GitHub
• تثبيت الـ dependencies عبر npm install
• إنشاء ملف .env وتعديل الإعدادات حسب الحاجة
• تشغيل الـ API عبر npm start ويكون متاح على localhost:5000
• استخدمه محليًا أو ارفعه على استضافة أو Server خاص بك

المساهمة

نرحب بأي مساهمة! إذا قابلت مشكلة أو لديك اقتراح يمكنك فتح issue على GitHub

روابط المشروع