Dorar.net Hadith API

السلام عليكم ورحمة الله وبركاته

منذ مدة حاولت استعمال الـ API الخاص بالدرر السنية
لكنني واجهت بعض الصعوبات منها أن الـ API يتعامل مع JSONP فقط وأيضًا لن تستطيع التعامل معه بالطرق العادية بسبب الـ CORS

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

فأنا قررت عمل API وسيط يتجنب مشكلة CORS ويعطيك البيانات كهيئة JSON بجانب شرح مفصل للـ API وكيفية استخدامه
بالاضافة إلى احتواءه على بعض الخصائص الإضافية التي لا توجد في الـ API الرسمي

تنبيه

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

يمكنك تعديلهم من ملف config.js

تشغيل الـ API

1. عمل fork أو clone لهذا المشروع
2. تثبيت الـ dependencies

npm install

3. تفقد ملف config.js وقم بتعديل ما تريده
4. تشغيل الـ API

npm start

5. الـ API سيكون متوفر على الرابط التالي

http://localhost:5000

6. استخدمه على localhost كما تريد أو ارفعه على استضافة أو سيرفر خاص بك

Documentation

Postman

الرابط: Postman

• استعمل Postman لتعرف كيف تتعامل مع الـ API وترى أمثلة عليه
• قم بعمل fork للـ collection لتستخدمه كما تريد
• لا تنس تغير الـ environment إلى dev ويمكنك تغير الرابط الخاص بالمتغير {{url}} ان كنت قد غيرته أو غيرت الـ port

OpenAPI v3 (Swagger)

وثائق API

لعرض وثائق API التفاعلية:

1. قم بتشغيل الخادم:

   npm run dev
   

2. افتح المتصفح وانتقل إلى:

   http://localhost:5000/api-docs
   

ستجد هنا واجهة Swagger UI التي تتيح لك استكشاف جميع نقاط النهاية المتاحة واختبار الـ API مباشرة من المتصفح.

Endpoints

يحتوي الـ API على مجموعة من الـ endpoint

• عندما يبدأ الـ endpoint بـ /api فهو هكذا يبحث عن طريق الـ API الرسمي الخاص بالدرر السنية
• عندما يبدأ الـ endpoint بـ /site فهو هكذا يبحث عن طريق صفحة البحث الخاص بالدرر السنية

/v1/api/hadith/search?value={text}

للبحث عن الأحاديث يعطي 15 نتيجة

شكل الرد كـ JSON

{
  "metadata": {
    "length": "عدد نتائج البحث",
    "page": "رقم الصفحة",
    "removeHTML": "هل عناصر الـ HTML ممسوحة أم لا",
    "isCached": "هل هذه النتائج من الـ cache أم لا"
  },
  "data": [
    {
      "hadith": "الحديث",
      "rawi": "الراوي",
      "mohdith": "المحدث",
      "book": "الكتاب",
      "numberOrPage": "رقم الحديث او الصفحة",
      "grade": "درجة الصحة"
    }
  ]
}

/v1/site/hadith/search?value={text}

للبحث عن الأحاديث يعطي 30 نتيجة

شكل الرد كـ JSON

{
  "metadata": {
    "length": "عدد نتائج البحث",
    "page": "رقم الصفحة",
    "removeHTML": "هل عناصر الـ HTML ممسوحة أم لا",
    "specialist": "نوع الاحاديث هل هي للمتخصصين أم لا",
    "numberOfNonSpecialist": "عدد الأحاديث لغير المتخصصين",
    "numberOfSpecialist": "عدد الأحاديث للمتخصصين",
    "isCached": "هل هذه النتائج من الـ cache أم لا"
  },
  "data": [
    {
      "hadith": "الحديث",
      "rawi": "الراوي",
      "mohdith": "المحدث",
      "mohdithId": "رقم المحدث",
      "book": "الكتاب",
      "bookId": "رقم الكتاب",
      "numberOrPage": "رقم الحديث او الصفحة",
      "grade": "درجة الصحة",
      "explainGrade": "توضيح درجة الصحة",
      "takhrij": "تخريج الحديث في كتب أخرى",
      "hadithId": "رقم الحديث لاستخدامه في البحث عن الأحاديث البديلة أو الحديث البديل الصحيح",
      "hasSimilarHadith": "هل الحديث له أحاديث مشابهة أم لا",
      "hasAlternateHadithSahih": "هل الحديث له حديث صحيح بديل أم لا",
      "similarHadithDorar": "رابط الأحاديث المشابهة في موقع الدرر",
      "alternateHadithSahihDorar": "رابط الحديث الصحيح في موقع الدرر",
      "urlToGetSimilarHadith": "رابط لكي تبحث عن الأحاديث المشابهة",
      "urlToGetAlternateHadithSahih": "رابط لكي تبحث عن الحديث الصحيح",
      "hasSharhMetadata": "هل الحديث له شرح أم لا",
      "sharhMetadata": {
        "id": "رقم الشرح",
        "isContainSharh": "هل يحتوى هذا الرد على شرح الحديث أم لا؟",
        "urlToGetSharh": "رابط لكي تبحث عن شرح الحديث"
      }
    }
  ]
}

/v1/site/hadith/similar/:id

يحضر لك أحاديث مشابهة المقابلة للـ id

شكل الرد كـ JSON

{
  "metadata": {
    "length": "عدد نتائج البحث",
    "isCached": "هل هذه النتائج من الـ cache أم لا"
  },
  "data": [
    {
      "hadith": "الحديث",
      "rawi": "الراوي",
      "mohdith": "المحدث",
      "mohdithId": "رقم المحدث",
      "book": "الكتاب",
      "bookId": "رقم الكتاب",
      "numberOrPage": "رقم الحديث او الصفحة",
      "grade": "درجة الصحة",
      "explainGrade": "توضيح درجة الصحة",
      "hadithId": "رقم الحديث لاستخدامه في البحث عن الأحاديث البديلة أو الحديث البديل الصحيح",
      "hasSimilarHadith": "هل الحديث له أحاديث مشابهة أم لا",
      "hasAlternateHadithSahih": "هل الحديث له حديث صحيح بديل أم لا",
      "similarHadithDorar": "رابط الأحاديث المشابهة في موقع الدرر",
      "alternateHadithSahihDorar": "رابط الحديث الصحيح في موقع الدرر",
      "urlToGetSimilarHadith": "رابط لكي تبحث عن الأحاديث المشابهة",
      "urlToGetAlternateHadithSahih": "رابط لكي تبحث عن الحديث الصحيح",
      "hasSharhMetadata": "هل الحديث له شرح أم لا",
      "sharhMetadata": {
        "id": "رقم الشرح",
        "isContainSharh": "هل يحتوى هذا الرد على شرح الحديث أم لا؟",
        "urlToGetSharh": "رابط لكي تبحث عن شرح الحديث"
      }
    }
  ]
}

/v1/site/hadith/:id

يحضر لك الحديث المقابل للـ id

شكل الرد كـ JSON

{
  "metadata": {
    "isCached": "هل هذه النتائج من الـ cache أم لا"
  },
  "data": {
    "hadith": "الحديث",
    "rawi": "الراوي",
    "mohdith": "المحدث",
    "mohdithId": "رقم المحدث",
    "book": "الكتاب",
    "bookId": "رقم الكتاب",
    "numberOrPage": "رقم الحديث او الصفحة",
    "grade": "درجة الصحة",
    "explainGrade": "توضيح درجة الصحة",
    "hadithId": "رقم الحديث لاستخدامه في البحث عن الأحاديث البديلة أو الحديث البديل الصحيح",
    "hasSimilarHadith": "هل الحديث له أحاديث مشابهة أم لا",
    "hasAlternateHadithSahih": "هل الحديث له حديث صحيح بديل أم لا",
    "similarHadithDorar": "رابط الأحاديث المشابهة في موقع الدرر",
    "alternateHadithSahihDorar": "رابط الحديث الصحيح في موقع الدرر",
    "urlToGetSimilarHadith": "رابط لكي تبحث عن الأحاديث المشابهة",
    "urlToGetAlternateHadithSahih": "رابط لكي تبحث عن الحديث الصحيح",
    "hasSharhMetadata": "هل الحديث له شرح أم لا",
    "sharhMetadata": {
      "id": "رقم الشرح",
      "isContainSharh": "هل يحتوى هذا الرد على شرح الحديث أم لا؟",
      "urlToGetSharh": "رابط لكي تبحث عن شرح الحديث"
    }
  }
}

/v1/site/hadith/alternate/:id

يحضر لك الحديث الصحيح المقابل للـ id

شكل الرد كـ JSON

{
  "metadata": {
    "isCached": "هل هذه النتائج من الـ cache أم لا"
  },
  "data": {
    "hadith": "الحديث",
    "rawi": "الراوي",
    "mohdith": "المحدث",
    "mohdithId": "رقم المحدث",
    "book": "الكتاب",
    "bookId": "رقم الكتاب",
    "numberOrPage": "رقم الحديث او الصفحة",
    "grade": "درجة الصحة",
    "hadithId": "رقم الحديث لاستخدامه في البحث عن الأحاديث البديلة أو الحديث البديل الصحيح",
    "hasSimilarHadith": "هل الحديث له أحاديث مشابهة أم لا",
    "hasAlternateHadithSahih": "هل الحديث له حديث صحيح بديل أم لا",
    "similarHadithDorar": "رابط الأحاديث المشابهة في موقع الدرر",
    "urlToGetSimilarHadith": "رابط لكي تبحث عن الأحاديث المشابهة",
    "hasSharhMetadata": "هل الحديث له شرح أم لا",
    "sharhMetadata": {
      "id": "رقم الشرح",
      "isContainSharh": "هل يحتوى هذا الرد على شرح الحديث أم لا؟",
      "urlToGetSharh": "رابط لكي تبحث عن شرح الحديث"
    }
  }
}

/v1/site/sharh/:id

للبحث عن شرح لحديث واحد عن طريق الـ id

شكل الرد كـ JSON

{
  "metadata": {
    "isCached": "هل هذه النتائج من الـ cache أم لا"
  },
  "data": {
    "hadith": "الحديث",
    "rawi": "الراوي",
    "mohdith": "المحدث",
    "book": "الكتاب",
    "numberOrPage": "رقم الحديث او الصفحة",
    "grade": "درجة الصحة",
    "takhrij": "تخريج الحديث في كتب أخرى",
    "hasSharhMetadata": "هل الحديث له شرح أم لا",
    "sharhMetadata": {
      "id": "رقم الشرح",
      "isContainSharh": "هل يحتوى هذا الرد على شرح الحديث أم لا؟",
      "urlToGetSharh": "رابط لكي تبحث عن شرح الحديث",
      "sharh": "شرح الحديث"
    }
  }
}

/v1/site/sharh/text/:text

للبحث عن شرح لحديث واحد عن طريقة النص المعطى

شكل الرد كـ JSON

{
  "metadata": {
    "specialist": "نوع الاحاديث هل هي للمتخصصين أم لا",
    "isCached": "هل هذه النتائج من الـ cache أم لا"
  },
  "data": {
    "hadith": "الحديث",
    "rawi": "الراوي",
    "mohdith": "المحدث",
    "book": "الكتاب",
    "numberOrPage": "رقم الحديث او الصفحة",
    "grade": "درجة الصحة",
    "takhrij": "تخريج الحديث في كتب أخرى",
    "hasSharhMetadata": "هل الحديث له شرح أم لا",
    "sharhMetadata": {
      "id": "رقم الشرح",
      "isContainSharh": "هل يحتوى هذا الرد على شرح الحديث أم لا؟",
      "urlToGetSharh": "رابط لكي تبحث عن شرح الحديث",
      "sharh": "شرح الحديث"
    }
  }
}

/v1/site/sharh/search?value={text}

للبحث عن شرح للأحاديث يعطي 30 نتيجة

شكل الرد كـ JSON

{
  "metadata": {
    "length": "عدد نتائج البحث",
    "page": "رقم الصفحة",
    "removeHTML": "هل عناصر الـ HTML ممسوحة أم لا",
    "specialist": "نوع الاحاديث هل هي للمتخصصين أم لا",
    "isCached": "هل هذه النتائج من الـ cache أم لا"
  },
  "data": [
    {
      "hadith": "الحديث",
      "rawi": "الراوي",
      "mohdith": "المحدث",
      "book": "الكتاب",
      "numberOrPage": "رقم الحديث او الصفحة",
      "grade": "درجة الصحة",
      "takhrij": "تخريج الحديث في كتب أخرى",
      "hasSharhMetadata": "هل الحديث له شرح أم لا",
      "sharhMetadata": {
        "id": "رقم الشرح",
        "isContainSharh": "هل يحتوى هذا الرد على شرح الحديث أم لا؟",
        "urlToGetSharh": "رابط لكي تبحث عن شرح الحديث",
        "sharh": "شرح الحديث"
      }
    }
  ]
}

/v1/site/mohdith/:id

للبحث عن معلومات عن المحدث عن طريق الـ id

شكل الرد كـ JSON

{
  "metadata": {
    "isCached": "هل هذه النتائج من الـ cache أم لا"
  },
  "data": {
    "name": "المحدث",
    "mohdithId": "رقم المحدث",
    "info": "معلومات عن المحدث"
  }
}

/v1/site/book/:id

للبحث عن معلومات عن الكتاب عن طريق الـ id

شكل الرد كـ JSON

{
  "metadata": {
    "isCached": "هل هذه النتائج من الـ cache أم لا"
  },
  "data": {
    "name": "الكتاب",
    "bookId": "رقم الكتاب",
    "author": "المؤلف",
    "reviewer": "المراجع",
    "publisher": "دار النشر",
    "edition": "رقم الطبعة",
    "editionYear": "سنة الطبعة"
  }
}

Query

عناصر الـ query التي يمكنك استخدامها
مع شرح تفصيلي أسفل الجدول

key	الوصف
value	وهي محتوى نص الحديث المراد البحث عنه
page	لتحديد الصفحة التي تريدها
removehtml	حذف عناصر الـ HTML في الحديث
specialist	تستخدم لتحدد نوع الاحاديث هل هي للمتخصصين أم لا
xclude	كلمة أو جملة تريد استبعادها من البحث
st	تحدد طريقة البحث
t	تحديد نطاق البحث
d[]	تحديد درجة الحديث سواء صحيح ام ضعيف
m[]	تحديد اسماء المحدثين التي تريدهم
s[]	تحديد الكتب التي تريد البحث فيها
rawi[]	تحديد اسماء الرواة التي تريدهم

• هذه الاقواس [] تفيد ان هذا العنصر يقبل اكثر من اختيار

value

• محتوى نص الحديث المراد البحث عنه
• مثال: /v1/api/hadith/search?value=جملة البحث
  هكذا سيبحث بناءًا على جملة البحث

page

• لتحديد الصفحة التي تريدها
• مثال: /v1/api/hadith/search?value=جملة البحث&page=1
  هكذا سيبحث في نتائج البحث للصفحة الثالثة أي المجموعة الثالثة لنتائج البحث
• القيمة الافتراضية ستكون الصفحة رقم واحد page=1

removehtml

• حذف عناصر الـ HTML في الحديث
  مثل <span class="search-keys">...</span>
• مثال: /v1/api/hadith/search?value=جملة البحث&removehtml=true
  هكذا سيمسح عناصر الـ HTML من نتائج البحث
• القيمة الافتراضي هي true

specialist

• تستخدم لتحدد نوع الاحاديث هل هي للمتخصصين أم لا
• قيمها هي true للمتخصصين و false لغير المتخصصين
• مثال: /v1/api/hadith/search?value=جملة البحث&specialist=true
  سيعطيك أحاديث أكثر ومختلفة خاصة للمتخصصين
  وتكون بها معلومة اضافية مثل تخريج الأحاديث في الكتب الأخرى
• القيمة الافتراضية هي false

xclude

• كلمة أو جملة تريد استبعادها من البحث مثال
• مثال: /v1/api/hadith/search?value=جملة البحث&xclude=اليهود
  هكذا سيستبعد كلمة اليهود من البحث

st

• تحدد طريقة البحث بثلاثة خيارات فقط
• هذه الطرق هي: جميع الكلمات، أي كلمة، بحث مطابق
• قيمها هي: w, a, p
  للبحث بـ جميع الكلمات فستكون st=w
  للبحث بـ أي كلمة فستكون st=a
  للبحث بـ بحث مطابق فستكون st=p
• مثال: /v1/api/hadith/search?value=جملة البحث&st=p
  هكذا سيبحث بشكل مطابق لجملة البحث

كل القيم وطرق البحث التي تمثلها
أو يمكنك الحصول عليها كملف JSON من هنا

t

• تحديد نطاق البحث
• هذه النطاقات هي: جميع الأحاديث، الأحاديث المرفوعة، الأحاديث القدسية، آثار الصحابة، شروح الأحاديث
• قيمها هي: *, 0, 1, 2, 3
  للبحث عن جميع الأحاديث فستكون t=*
  للبحث عن الأحاديث المرفوعة فستكون t=0
  للبحث عن الأحاديث القدسية فستكون t=1
  للبحث عن آثار الصحابة فستكون t=2
  للبحث عن شروح الأحاديث فستكون t=3
• مثال: /v1/api/hadith/search?value=جملة البحث&t=1
  هكذا سيبحث فقط عن الأحاديث القدسية المطابق لجملة البحث

كل القيم ونطاقات البحث التي تمثلها
أو يمكنك الحصول عليها كملف JSON من هنا

d[]

• تحديد درجة الحديث سواء صحيح ام ضعيف
• قيمها هي: 0، 1، 2، 3، 4
  للبحث عن جميع الدرجات فستكون d[]=0
  للبحث عن أحاديث حكم المحدثون عليها بالصحة فستكون d[]=1
  للبحث عن أحاديث حكم المحدثون على أسانيدها بالصحة فستكون d[]=2
  للبحث عن أحاديث حكم المحدثون عليها بالضعف فستكون d[]=3
  للبحث عن أحاديث حكم المحدثون على أسانيدها بالضعف فستكون d[]=4
• مثال: /v1/api/hadith/search?value=جملة البحث&d[]=3
  هكذا سيبحث فقط عن الأحاديث المحكوم عليها بالضعف
• يمكنك تحديد اكثر من اختيار
  مثال: /v1/api/hadith/search?value=جملة البحث&d[]=1&d[]=2
  هكذا سيبحث فقط عن الأحاديث المحكوم عليها بالصحة من ناحية المتن و الاسناد

كل القيم والدرجات التي تمثلها
أو يمكنك الحصول عليها كملف JSON من هنا

m[]

• تحديد اسماء المحدثين التي تريدهم
• قيمها متعددة ومنها: 0، 179، 204، 256، 261 ... إلخ
  حيث 0 تمثل جميع المحدثين
  و179 تمثل الإمام المالك
  و204 تمثل الإمام الشافعي
  و256 تمثل البخاري
  و261 تمثل مسلم
• مثال: /v1/api/hadith/search?value=جملة البحث&m[]=179
  هكذا سيبحث فقط عن الأحاديث التي حدث بها الإمام مالك
• يمكنك تحديد اكثر من اختيار
  مثال: /v1/api/hadith/search?value=جملة البحث&m[]=256&m[]=261
  هكذا سيبحث فقط عن الأحاديث التي حدثا بها بخاري ومسلم

كل القيم وأسماء المحدثين التي تمثلها
أو يمكنك الحصول عليها كملف JSON من هنا

s[]

• تحديد الكتب التي تريد البحث فيها
• قيمها متعددة ومنها: 0، 13457، 6216، 3088، 96 ... إلخ
  حيث 0 تمثل جميع المحدثين و13457 تمثل الأربعون النووية
  و6216 تمثل صحيح البخاري
  و3088 تمثل صحيح مسلم
  و96 تمثل الصحيح المسند
• مثال: /v1/api/hadith/search?value=جملة البحث&s[]=96
  هكذا سيبحث فقط عن الأحاديث الواردة في كتاب الصحيح المسند
• يمكنك تحديد اكثر من اختيار
  مثال: /v1/api/hadith/search?value=جملة البحث&s[]=6216&s[]=13457
  هكذا سيبحث فقط عن الأحاديث التي وردت في كتابي الأربعون النووية وكتاب صحيح البخاري

كل القيم وأسماء الكتب التي تمثلها
أو يمكنك الحصول عليها كملف JSON من هنا

rawi[]

• تحديد اسماء الرواة التي تريدهم
• قيمها متعددة ومنها: 0،1819، 8918، 2664 ... إلخ
  حيث 0 تمثل جميع الرواة
  حيث 1819 تمثل أسماء بنت أبي بكر
  و8918 تمثل عمر بن الخطاب
  و2664 تمثل ابن عباس
• مثال: /v1/api/hadith/search?value=جملة البحث&rawi[]=1819
  هكذا سيبحث فقط عن الأحاديث التي رواتها أسماء بنت أبي بكر
• يمكنك تحديد اكثر من اختيار
  مثال: /v1/api/hadith/search?value=جملة البحث&rawi[]=8918&rawi[]=2664
  هكذا سيبحث فقط عن الأحاديث التي رواها عمر بن الخطاب وابن عباس
• هنا قيم ترمز لأكثر من شخص في آن واحد
  مثل 2665 ترمز لـ ابن عباس أو أبو هريرة
  و8924 ترمز لـ عمر بن الخطاب وأبو هريرة
  و264 ترمز لـ أبو الدرداء وأبو أمامة وعبدالله بن عمر وابن عباس وجابر بن عبدالله

كل القيم وأسماء الرواة التي تمثلها
أو يمكنك الحصول عليها كملف JSON من هنا

Data

كل البيانات المتاحة والقيم التي تمثلها يمكنكم الحصول عليه من هذه الـ endpoints

[
  {
    "endpoint": "/v1/data/book",
    "description": "احضار كل الكتب المتاحة",
    "abstractResponse": [
      {
        "key": "الكلمة  المفتاحية",
        "value": "القيمة"
      }
    ]
  },
  {
    "endpoint": "/v1/data/degree",
    "description": "احضار كل درجات الحديث المتاحة",
    "abstractResponse": [
      {
        "key": "الكلمة  المفتاحية",
        "value": "القيمة"
      }
    ]
  },
  {
    "endpoint": "/v1/data/methodSearch",
    "description": "احضار كل طرق البحث المتاحة",
    "abstractResponse": [
      {
        "key": "الكلمة  المفتاحية",
        "value": "القيمة"
      }
    ]
  },
  {
    "endpoint": "/v1/data/mohdith",
    "description": "احضار كل المحدثين المتاحين",
    "abstractResponse": [
      {
        "key": "الكلمة  المفتاحية",
        "value": "القيمة"
      }
    ]
  },
  {
    "endpoint": "/v1/data/rawi",
    "description": "احضار كل الرواة المتاحين",
    "abstractResponse": [
      {
        "key": "الكلمة  المفتاحية",
        "value": "القيمة"
      }
    ]
  },
  {
    "endpoint": "/v1/data/zoneSearch",
    "description": "احضار كل نطاقات البحث المتاحة",
    "abstractResponse": [
      {
        "key": "الكلمة  المفتاحية",
        "value": "القيمة"
      }
    ]
  }
]

توجد مشكلة أو لديك اقتراح؟

افتح issue إذا قابلت مشكلة ما او لديك اقتراح

المساهمة

بالطبع نرحب بأي مساهمة لدينا ❤