توثيق مطوّري أمل

أمل هو نظام القرار لمحو الأمية العربية، الموجَّه للمعلمين في العالم العربي. يوثّق هذا الموقع واجهته البرمجية (API): واجهة REST + JSON، موصوفة بالكامل عبر مواصفة OpenAPI 3.1.

يوثّق هذا الموقع طبقتين. طبقة التزويد (المصادقة، والبنية المستأجِرة للمؤسسات والمدارس والصفوف، وإدارة المستخدمين) مشروحة في البدء السريع والأدلة. أما محرّك الاستجابة للتدخّل القائم على القياس (حلقة التشخيص، وقرارات حالة المهارة، وملفات الطلاب، وحزم التدخّل، ومراقبة التقدّم، والتقارير) فقد أُطلق الآن ويُوثَّق في كيف تعمل المرحلة الأولى وأدلة كل نظام فرعي.

جديد على المنصّة؟ اقرأ كيف تعمل المرحلة الأولى ← حلقة الاستجابة للتدخل للقصّة الكاملة من طرف إلى طرف قبل التعمّق في أي نظام فرعي بمفرده.

الرابط الأساسي والإصدار

تُقدَّم الواجهة تحت المسار /api. المواصفة الحالية هي version: 1.0.0-phase0. الموجة الأولى موقع توثيق واحد غير مُصدَّر؛ والمسار /v1/… محجوز لإصدار مستقبلي مُصدَّر من الواجهة.

في كامل هذا التوثيق يُكتب الرابط الأساسي بصيغة http://localhost:8787 (المنفذ الافتراضي 8787؛ قابل للضبط عبر متغير البيئة PORT)، استبدله بعنوان خادمك apps/server. يعمل خادم التطوير الخاص بـ Next.js على المنفذ 3000 — لا تخلط بين الاثنين.

كيف تُجمَّع الواجهة

تُجمَّع العمليات حسب الوسم؛ ويعرضها مرجع الواجهة البرمجية بهذا الشكل. وسوم التزويد:

auth: التسجيل، تسجيل الدخول، التجديد، me، تسجيل الخروج، إعادة تعيين كلمة المرور، رمز الطالب السريع. انظر المصادقة.
tenancy: المؤسسات، المدارس، الصفوف، التجميع المؤسسي. انظر المفاهيم الأساسية.
users: التزويد، ملفات الأدوار، القوائم، المدراء، المنسقون، روابط أولياء الأمور. انظر إنشاء المستخدمين.
system: فحص الجاهزية.

أما وسوم محرّك الاستجابة للتدخّل والوسوم الداعمة (diagnostic-session وpractice وengine وsub-skills وsse وprofile وbundle وcluster وworkflow وmonitoring وorf وcbm وstandards وdelivery وreporting وparent-pdf وwarmup وlanguage-safety وqa وlogging وgamification وleaderboard وnotifications وlms وsession-catalog وsync وfidelity وrti وdata-room وdecision-packet وaudit وblob وpaper-results وonboarding وstudent-flow وparent-portal وغيرها) فجميعها مُعروضة في مرجع الواجهة البرمجية. ابدأ بـ كيف تعمل المرحلة الأولى لترى كيف تترابط.

المصادقة بجملة واحدة

كل طلب بعد تسجيل الدخول يحمل رمز Bearer JWT: Authorization: Bearer <accessToken>. انظر المصادقة للنموذج الكامل.

الاصطلاحات

الأجسام والاستجابات بصيغة JSON.
كل خطأ يستخدم مغلَّفًا واحدًا: { code, message, details?, retryAfter? }. انظر الأخطاء.
نوعان من المعرّفات، بحسب التصميم. موارد البنية المستأجِرة (المؤسسة، المدرسة، الصف) تستخدم معرّفات cuid نصّية تطابق ^c[a-z0-9]{24}$. أما المستخدمون وملفات الأدوار فيستخدمون معرّفات عددية صحيحة. لا تفترض نوعًا واحدًا في كامل الواجهة: معرّف الصف نصّ cuid، ومعرّف المستخدم عدد صحيح.

من أين تبدأ

جديد هنا؟ انتقل مباشرةً إلى البدء السريع، يمشي بك من تزويد المسؤول الأول حتى أول طلب مُصادَق عليه، بأمثلة جاهزة للنسخ تعمل مع خادم قيد التشغيل.