تخطَّ إلى المحتوى
دليل وقار

استخدام موارد API وقار

كل معرّفات الموارد مقيدة بالمستأجر. اقرأها من استجابات المدرسة المصادق عليها، ولا تكوّن معرّفاً من مدرسة أخرى أو تعِد استخدامه.

المدرسة والفصول

Section titled “المدرسة والفصول”
  • يعيد GET /school المدرسة المرتبطة بالمفتاح.
  • يسرد GET /semesters الفصول المخططة أو النشطة أو المؤرشفة.
  • يعيد GET /semesters/{id} فصلاً واحداً.

استخدم الفصل النشط للعمل الحالي، واحتفظ بمعرّفات المؤرشف عند مزامنة التاريخ.

الحلقات والشيوخ

Section titled “الحلقات والشيوخ”
  • يدعم GET /halqas مرشحات النشاط والفصل والمزامنة.
  • يعيد GET /halqas/{id} حلقة واحدة خاصة بفصل.
  • GET /sheikhs اكتشاف للأهلية الحالية، ويمكن ترشيحه بالحلقة.
  • يعيد GET /sheikhs/{id} شيخاً مؤهلاً حالياً.

يربط lineage_id للحلقة السجلات المنقولة بين الفصول. واكتشاف الشيخ ليس موجز مزامنة تزايدياً.

الطلاب

Section titled “الطلاب”
  • يدعم GET /students مرشحات الحالة والحلقة والفصل والمزامنة.
  • يعيد GET /students/{id} طالباً واحداً.
  • ينشئ POST /students طالباً عندما تكون الكتابة فعالة.
  • يحدث PATCH /students/{id} الحقول الموثقة.

يربط lineage_id للطالب السجلات الخاصة بالفصول. ويحذف API v1 حقول الطالب الحساسة. لا تستخدم null إلا حيث يسمح بها مخطط التحديث صراحة.

الجلسات والحضور والتلاوات

Section titled “الجلسات والحضور والتلاوات”
  • يقرأ GET /sessions وGET /sessions/{id} الجلسات.
  • تنفذ POST /sessions وPATCH /sessions/{id} و POST /sessions/{id}/end تغييرات دورة الحياة المدعومة.
  • يقرأ GET /sessions/{id}/attendance حضور الجلسة.
  • ينشئ PUT /sessions/{id}/attendance سجلات الطلاب المرسلين أو يحدّثها، ويبقي سجلات الحضور غير المرسلة بلا تغيير.
  • يسرد GET /sessions/{id}/recitations تلاوات الجلسة.
  • يسرد GET /students/{id}/recitations تلاوات الطالب.
  • يسجل POST /sessions/{id}/recitations تلاوة في جلسة.

يجب أن تستخدم الجلسة حلقة وشيخاً مؤهلين. ويجب أن يكون طالب الحضور أو التلاوة مؤهلاً للجلسة. ويتحقق وقار من التقييم ونطاق القرآن مقابل العقد والسياق.

مرجع القرآن

Section titled “مرجع القرآن”
  • يعيد GET /surahs مجموعة السور المحدودة كاملة.
  • يعيد GET /surahs/{number} سورة من 1 إلى 114.

تتطلب هذه العمليات مفتاحاً مصادقاً، ولا تتطلب نطاق مورد إضافياً. ولا تقبل مرشحات مجموعة أو ترقيم مؤشرات.

معالجة الاستجابة

Section titled “معالجة الاستجابة”

تستخدم الموارد المفردة {"data": {...}}، وتستخدم المجموعات {"data": [...], "pagination": {...}}. احفظ المعرّفات والأوقات الدقيقة، ولا تستخدم أسماء العرض كمعرّفات.

لخطط التعلّم دليل قراءة مستقل. ولكل طريقة ونطاق استخدم مرجع نقاط النهاية.