السلام عليكم ورحمة الله وبركاته،
هذه قصةُ خدمةٍ لم نخطِّط لها ابتداءً، وإنما دلَّتنا عليها إحصائيات استخدام API الموسوعة.
منذ مدَّةٍ صرنا نرى في سجلَّات الواجهة البرمجية (API) عملاءَ يتجاوز الواحدُ منهم المليونَ طلب، يمشي على الموقع مَشْيًا منظَّمًا: آيةً آيةً، وخدمةً خدمة، وكتابًا كتابًا، حتى يستوعبَ المحتوى كلَّه.
ولم يكن ذلك عبثًا ولا هجومًا؛ فنمَطُ الطلبات يكشف عن الهدف: أحدُهم أراد نسخةً كاملةً من البيانات ليبنيَ عليها شيئًا، فلم يجد أمامه إلا الطريقَ الطويل.
والذي استوقفَنا ليس الرقمَ في ذاته، بل أنَّ هذا الجهد كلَّه — على ثِقَله علينا وعليه — كان يُنتِج في آخره نسخةً رديئة.
لِمَ يحتاج الأمر إلى مليون طلبٍ أصلًا؟
لأنَّ الواجهة البرمجية مبنيَّةٌ على وَحدة الآية؛ أي: كلُّ طلبٍ يخدم آيةً واحدة بخدمةٍ واحدة. فإذا أردتَ المحتوى كلَّه، فالحسبةُ هكذا:
| المطلوب | الحساب | عدد الطلبات |
|---|
| خدمات الآيات (تفسير، إعراب، أسباب نزول، موضوعات، قراءات، ترجمات…) | 6236 آية × 14 خدمة | 87,304 |
| محتوى الكتب (نحو 150 كتابًا لها محتوًى مرتبطٌ بالآيات) | 6236 آية × 150 كتابًا | 935,400 |
| المجموع | | +1,000,000 |
فالمليون ليس مبالغةً في الوصف، بل هو الحدُّ الأدنى الذي لا بدَّ منه لمن أراد استيعابَ المحتوى من الواجهة البرمجية. وهو — مع ذلك — طريقٌ خاسرٌ من ثلاثة أوجه:
- على المستهلِك: مئاتُ الساعات، وآلافُ الطلبات المتقطِّعة، ونسخةٌ ناقصةٌ إن انقطع الاتصالُ في المنتصف، ولا يدري أين وقف.
- علينا: حِملٌ لا يُنتفَع به، يُبطئ الموقعَ ويزيد العبء على الخادن.
- على البيانات نفسها: وهذا أهمُّها. فمحتوى الموسوعة يُصحَّح باستمرار — خطأٌ في ضبطٍ، أو نصٌّ يُراجَع، أو تخريجٌ يُستدرَك — والنسخةُ المسحوبةُ آليًّا تتقادَم من يومها، ولا يملك صاحبُها طريقًا يعرف به ما الذي تغيَّر.
فالمشكلة إذن ليست في «الزحف» (crawling) نفسه، وإنما في أنَّنا لم نكن نُقدِّم للناس البابَ الذي يحتاجون إليه، فدخلوا من النافذة.
ما صنعناه — صفحة البيانات
فتحنا البابَ الصحيح، وهو صفحة:
https://api.quranpedia.net/dumps
وهي ملفَّاتٌ رسمية، مضغوطة، مُرقَّمةُ الإصدارات، تُبنى آليًّا وتُحدَّث كلَّما صُحِّح المحتوى، وتُنزَّل مجَّانًا بلا تسجيلٍ ولا مفتاح.
وأهمُّ ما فيها أنَّها بصيغة الواجهة البرمجية نفسِها؛ أي: الملفُّ المنزَّل يحمل الحقولَ ذاتها التي كنتَ ستحصل عليها لو استدعيتَ /v1/… مليونَ مرة، بحرفها. وهذا مقصودٌ في البناء: الملفَّات تُولَّد من الكود نفسه التي المستخدم للواجهة البرمجية.
** يشمل الرابط اليوم 193 ملفًّا، هذا بيانُها:**
| القسم | العدد | الحجم | ما فيه |
|---|
| المصاحف | 12 مصحفًا | 4.7MB | نصُّ القرآن كاملًا على روايات حفص وورش وقالون والدوري والسوسي والبَزِّي وقُنبُل وشعبة، ومعه مصحف التجويد الملوَّن، مع خيارات كل آية |
| كتب التفسير | 149 كتابًا | 899MB | لكلِّ كتابٍ ملفٌّ فيه محتواه في الآيات كلِّها — من "تفسير السمعاني" إلى "المنتخب" |
| خدمات الآيات | 14 خدمة | 26.5MB | لكلِّ خدمةٍ ملفٌّ يعُمُّ الآيات كلَّها: التفسير، والإعراب، وأسباب النزول، ومتشابه القرآن، والناسخ والمنسوخ، وغريب القرآن، والموضوعات، والفتاوى، والوقفات التدبرية، والمتشابهات، والقراءات، والترجمات، والتحليل الصرفي، والإعراب النحوي |
| كتب الترجمة | 138 ملفًّا | 61MB | لكلِّ ترجمةٍ ملفٌّ مستقلٌّ جاهز، فيه نصُّ كل آية مترجَمًا |
| كتب الإعراب | 4 كتب | 4.8MB | منها "التبيان في إعراب القرآن" للعُكبَري |
| أسباب النزول | كتابان | 0.7MB | "أسباب نزول القرآن" للواحدي، و"المحرر" |
| الناسخ والمنسوخ | كتاب | 0.1MB | "الإيضاح لناسخ القرآن ومنسوخه" |
| الفهارس | — | 7MB | معلومات السور الـ114، وفهرس الكتب والكتب المرتبطة، والفتاوى كلُّها (3.8MB — بما لم يُربَط بآية)، والموضوعات، والقُرَّاء، والتصنيفات |
ولمن أراد المحتوى كاملًا:
-
core-all.zip — 38 ميجابايت، فيها كلُّ شيءٍ سوى محتوى الكتب: نصُّ القرآن، ومعلومات السور، وخدمات الآيات الأربع عشرة، والفهارس. وهذه وحدَها تُغني عن أكثر من ثمانين ألف طلب، وهي الأنسب لأكثر التطبيقات.
-
complete-all.zip — نحو جيجابايت واحد، فيها المحتوى كلُّه بما فيه كتب التفسير. وهي تُغني عن المليون طلبٍ كلِّه، في رابط واحد.
وثَمَّ حُزَمٌ لكلِّ قسمٍ على حِدَة إن أردتَ بعضًا دون بعض: mushafs-all.zip، وservices-all.zip، وtafsir_books-all.zip، وtranslations-all.zip، وغيرُها.
كيف تستعملها؟
ابدأ من الفهرس:
GET https://api.quranpedia.net/dumps/manifest.json
وفيه لكلِّ ملفٍّ: اسمُه، وقِسمُه، وحجمُه، وتاريخُ بنائه (built_at)، وبصمتُه (sha256) للتحقُّق من سلامة التنزيل. وفي أعلاه رقمُ الإصدار (version)، وحقلُ coverage_since؛ أي: تاريخُ بناء أقدم ملفٍّ في هذه النسخة.
فإذا أردتَ أن تبقى على الجديد بعد التنزيل، فلا تُعِد السحبَ من أوَّله، وإنما اسأل مسارَ التغييرات:
GET https://api.quranpedia.net/v1/changes?since=YYYY-MM-DD
فيَرُدُّ عليك بما تغيَّر منذ ذلك التاريخ، ومع كلِّ عنصرٍ مسارُ refetch الخاصُّ به، فتجلب المتغيِّرَ وحدَه. وبهذا تكون النسخةُ عندك حيَّةً لا جامدة، وهو المقصودُ الأكبر من الخدمة كلِّها.
الرخصة
مجَّانيةٌ للاستعمال، ولم نجعلها مقيَّدة:
- داخل التطبيقات: لا يلزمك إسنادٌ ولا ذِكرُ مصدر (وإن ذكرتَه، فمشكورٌ مأجور، وهو غيرُ مشروط).
- إعادة النشر — أن تنشر البيانات نفسَها قاعدةً قابلةً للتنزيل، كاملةً أو بعضَها —: يلزم فيها ذِكرُ «الموسوعة القرآنية quranpedia.net» مع الرابط ورقم الإصدار؛ لأنَّ المحتوى يُصحَّح، فذِكرُ الإصدار يحفظ على الناس أن ينسبوا إلينا خطأً قد صحَّحناه.
ونصُّ الرخصة مُضمَّنٌ في كل ملفٍّ نفسِه، وفي LICENSE.md.
حدود الاستعمال لخدمة API
الواجهةُ البرمجية مفتوحةٌ ومجَّانية، وحدودُها واسعةٌ لكل استعمالٍ طبيعي: 120 طلبًا في الدقيقة، وعشرة آلاف طلبٍ في اليوم — وهو أضعافُ ما يحتاجه أيُّ تطبيقٍ رأيناه.
وإنما وُضِعت هذه الحدودُ لتقول للساحب الآلي: «لستَ في المكان الصحيح». ولذلك جعلنا رسالةَ الرفض (429) نفسَها تدلُّ على صفحة البيانات وعلى مسار التغييرات، لا أن تقف عند المنع.
فإن كانت لك حاجةٌ لا تفي بها الحدودُ ولا الملفَّات، فراسِلنا؛ فالباب مفتوح: quranpedia.help@gmail.com
خاتمة: ما نطلبه منكم
الخدمةُ جديدةٌ، ونحن نبنيها على ما يَرِد إلينا من حاجات إخواننا المطوِّرين، فأفيدونا:
- ما البياناتُ التي تحتاجها ولم تجدها في القائمة؟
- هل الصيغةُ (JSON على صيغة الواجهة) مناسبةٌ لك، أم تحتاج إلى صيغةٍ أخرى — SQLite مثلًا، أو CSV؟
- هل جرَّبتَ مسارَ
/v1/changes؟ وهل أدَّى الغرضَ في المزامنة؟
وإن كنتَ ممَّن سحَب بياناتِنا سابقًا بالطريقة الطويلة، فلا بأس عليك؛ فالتقصيرُ كان منَّا في ألَّا نُيسِّر لك الطريق. وهذه الملفَّاتُ اعتذارٌ عمليٌّ قبل أن تكون خدمة.
والحمد لله أوَّلًا وآخِرًا.
الروابط:
