تنفيذ كتابات آمنة مانعة للتكرار

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

• إنشاء طالب أو تحديثه.
• إنشاء جلسة أو تحديثها أو إنهاؤها.
• إنشاء حضور الطلاب المرسلين في جلسة أو تحديثه في دفعة واحدة، مع إبقاء حضور الطلاب غير المرسلين بلا تغيير.
• تسجيل تلاوة في جلسة.

خطط التعلّم للقراءة فقط في API v1.

• استخدم Content-Type: application/json.
• أبقِ الجسم الكامل عند 1 MiB أو أقل.
• لا ترسل إلا الحقول المعرفة في المخطط الحالي؛ فالحقول المجهولة مرفوضة.
• استخدم قيم التعداد وUUID والتاريخ والنطاق القرآني والتقييم الموثقة.
• تحتوي دفعة الحضور من طالب واحد إلى 1,000 طالب فريد.
• يعني غياب الحقل في patch «لا تغيره»، وقد تمحو null الصريحة المدعومة حقلاً قابلاً للقيمة الفارغة.

تتطلب عمليات الإنشاء POST وPUT للحضور ترويسة Idempotency-Key. يجب أن تكون القيمة من 1 إلى 255 محرف ASCII مرئياً (من ! إلى ~، ولا تُقبل المسافات). وتقبل تحديثات الطالب والجلسة وإنهاء الجلسة الترويسة اختيارياً.

لكل عملية منطقية:

1. ولّد قيمة عالية العشوائية في الخدمة المستدعية.
2. خزّنها مع المهمة المعلقة قبل الإرسال.
3. أرسل القيمة نفسها مع الطريقة والمسار والاستعلام والجسم نفسها عند الإعادة.
4. أبقها خارج السجلات والتتبعات والعناوين وواجهات المستخدم.
5. احتفظ بالربط طوال نافذة إعادة وقار البالغة سبعة أيام.

تعيد المحاولة المطابقة الناجحة الاستجابة المحفوظة. وينتج عن استخدام القيمة لطلب مختلف 409 idempotency_key_conflict. وقد ينتج عن طلب متزامن مكرر 409 idempotency_request_in_progress؛ انتظر Retry-After ثم أعد الطلب نفسه.

1. اقرأ معرّفات المتطلبات وتحقق منها في المستأجر نفسه.
2. تحقق محلياً من الجسم مقابل OpenAPI.
3. أرسل مفتاح أقل صلاحية وقيمة منع التكرار.
4. عند 201 خزّن data.id وLocation الناتجين.
5. عند 200 طابق المورد الناتج.
6. عند 422 صحح إدخال العمل؛ ولا تعِده بلا تغيير.
7. عند 409 ميّز تعارض دورة الحياة من سلوك منع التكرار.
8. عند فشل نقل غير محسوم، لا تعِد إلا بالقيمة الأصلية والطلب المطابق.
9. أتبع ذلك بقراءة عندما يحتاج التكامل إلى تأكيد دائم.

لا تحوّل كتابة مرفوضة إلى تغييرات غير موثقة. راجع الأخطاء والحصص والموارد.