Idempotency

كيفية الاستخدام

POST /v1/chart HTTP/1.1
X-Api-Key: aw_live_...
Idempotency-Key: 01HXY2A7ZM0ABCDEF
Content-Type: application/json

{ "datetime": "1990-07-14T14:30:00", ... }

Idempotency-Key هو سلسلة عشوائية تصل إلى 64 حرفًا، فريدة لكل عملية منطقية. موصى به: ULID أو UUID v4.

الضمانات

• خلال 24 ساعة بعد الطلب الأول بهذا المفتاح، الطلبات المتكررة بنفس المفتاح تعيد نفس الاستجابة دون إعادة الحساب وبدون خصم الاعتمادات.
• إذا كان نص الطلب يختلف عن الأصلي: يتم إرجاع 409 Conflict بالرمز idempotency_key_reuse.
• بعد 24 ساعة، يتم نسيان المفتاح، والطلب الجديد بنفس المفتاح سيكون عاديًا.

ملاحظة

الإبدومبوتنس حماية من الخصم المزدوج أثناء فشل الشبكة، وليست التخزين المؤقت. للتخزين المؤقت، استخدم آلية X-Cache الطبيعية (5 دقائق، انظر الاعتمادات والحدود).

متى تحتاج إليه

• في معالجات الويب هوك، حيث يأتي الإعادة من نظام خارجي (مثل مزود الدفع أو CRM يرسل حدثًا تقوم بتحليله وإجراء الحساب)
• في الوظائف الخلفية، حيث الإعادة هي السلوك الافتراضي عند الفشل
• في خط أنابيب CI/CD، حيث يمكن تشغيل الاختبار مرة أخرى

للتفاعلات العادية “نقر المستخدم على الزر → عرض الخريطة”، الإبدومبوتنس غير مطلوب - المستخدم سيشاهد النتيجة على أي حال، عادةً لا توجد نقرات مكررة.

متى لا تستخدمه

• لا تضع مفتاحًا لتوفير الاعتمادات في الطلبات المتطابقة: لهذا الغرض يوجد X-Cache (مجاني، 5 دقائق)
• لا تولد مفتاحًا من hash(body): ستفقد سلوك الإبدومبوتنس الافتراضي (409 متكرر عند اختلاف الـ body)