واجهة البرمجة العامة

واجهة JSON عامة للقراءة فقط، بلا مصادقة وبلا حدود استخدام. كل المحتوى بالعربية.

البداية

العنوان الأساسي هو https://sehraltaqa.com. كل الاستجابات على الشكل التالي:

{ "data": ..., "meta": { "page": 1, "limit": 20, "total": 1020 } }

الأخطاء تأتي بالشكل { "error": { "status": 404, "message": "..." } }. القيم خارج المدى المسموح لـ limit وpage تُقصّ إلى أقرب قيمة صالحة ولا تُرفض.

الوصف الآلي متاح في openapi.json (OpenAPI 3.1)، والفهرس الآلي في ‎/.well-known/api-catalog‎، وجرد المحتوى للنماذج اللغوية في llms.txt.

نقاط النهاية

GET/api/public/articles

قائمة المقالات مرتبة من الأحدث. لا تتضمن نص المقال.

المعاملات: page (≥ 1) · limit (1–100، الافتراضي 20) · category (معرّف التصنيف)

curl -s 'https://sehraltaqa.com/api/public/articles?limit=5'

GET/api/public/articles/{slug}

مقال واحد مع نصه الكامل في الحقل body.

curl -s 'https://sehraltaqa.com/api/public/articles/{slug}'

GET/api/public/questions

قائمة صفحات الأسئلة والأجوبة. لا تتضمن الأسئلة نفسها.

المعاملات: page · limit · category

curl -s 'https://sehraltaqa.com/api/public/questions?limit=5'

GET/api/public/questions/{slug}

صفحة أسئلة واحدة مع كل سؤال وجوابه في questionBlocks.

curl -s 'https://sehraltaqa.com/api/public/questions/{slug}'

GET/api/public/authors

قائمة الكتّاب.

المعاملات: page · limit

curl -s 'https://sehraltaqa.com/api/public/authors'

GET/api/public/authors/{slug}

كاتب واحد مع روابط التواصل. يعمل حتى لو لم يكن للكاتب محتوى منشور.

curl -s 'https://sehraltaqa.com/api/public/authors/{slug}'

GET/api/public/categories

كل التصنيفات. مرّر contentType للحصول على عدد العناصر في كل تصنيف.

المعاملات: contentType (article | question-page)

curl -s 'https://sehraltaqa.com/api/public/categories?contentType=article'

GET/api/public/search

بحث نصي في المقالات وصفحات الأسئلة. المحتوى عربي، فابحث بالعربية.

المعاملات: q (مطلوب) · limit (1–100، الافتراضي 5 لكل نوع محتوى)

curl -s 'https://sehraltaqa.com/api/public/search?q=الطاقة'

النصوص الغنية: blocks JSON

الحقل body في المقال، والحقل answer داخل questionBlocks، ليسا نصًا ولا HTML، بل مصفوفة كتل من Strapi:

{
  "type": "paragraph",
  "children": [{ "type": "text", "text": "نص عربي" }]
}

للحصول على نص عادي، اجمع كل children[].text بشكل تكراري، لأن children قد تحتوي على children أخرى. قيم type الموجودة في المحتوى: heading (مع level)، paragraph، list، quote، image، code، link.

الحصول على الصفحات بصيغة Markdown

أي صفحة في الموقع يمكن استرجاعها بصيغة Markdown بدل HTML، إما بإرسال ترويسة Accept: text/markdown أو بإضافة .md إلى نهاية الرابط. هذا عادةً أسرع طريق للنص القابل للقراءة، ويغنيك عن معالجة blocks JSON:

curl -s -H 'Accept: text/markdown' 'https://sehraltaqa.com/articles/{slug}'
curl -s 'https://sehraltaqa.com/articles/{slug}.md'

الاستجابة تبدأ بترويسة YAML فيها العنوان والوصف والرابط، ثم النص، ثم بيانات JSON-LD الخاصة بالصفحة.

الترويسات والتخزين المؤقت

كل استجابة تحمل Access-Control-Allow-Origin: *، وCache-Control: public, s-maxage=300, stale-while-revalidate=3600، وLink: </openapi.json>; rel="service-desc".

حدود الاستخدام

لا توجد حدود معلنة حاليًا. نرجو الالتزام بمعدل معقول، واحترام robots.txt وما تعلنه من إشارات المحتوى.