Idempotency-Key

ترويسة Idempotency-Key Idempotency-Key

ترويسة يولّدها العميل لجعل طلبات POST غير الآمنة قابلة لإعادة المحاولة بأمان دون تكرار العملية الفعلية.

بخلاف GET وPUT وDELETE، فإن POST ليست عديمة الأثر التراكمي — إن انقطع الاتصال قبل وصول الرد وأعاد العميل المحاولة، قد ينشئ الخادم سجلًا مكررًا (طلب دفع مزدوج مثلًا). ترويسة Idempotency-Key — الموصوفة في مسودة معيار IETF لـ HTTP APIs — تحل هذه المشكلة: يولّد العميل قيمة فريدة (عادة UUID) لكل عملية منطقية واحدة، ويرسلها مع كل محاولة لنفس الطلب.

يخزّن الخادم نتيجة أول تنفيذ مرتبطة بهذا المفتاح؛ فإن وصل طلب لاحق بنفس المفتاح، يعيد الخادم النتيجة المخزَّنة بدل تنفيذ العملية من جديد. المفتاح نفسه يجب ألا يُعاد استخدامه مع جسم طلب مختلف — هذا يُعتبر خطأ من العميل. هذا النمط شائع جدًا في واجهات الدفع (Stripe وغيرها) حيث يكون تكرار العملية خطأً باهظ الثمن.

الصياغة

POST /resource
Idempotency-Key: <معرّف فريد لكل عملية>
Content-Type: application/json

{ ... }

📄 مثال

POST /api/payments HTTP/1.1
Idempotency-Key: 6c1f6b2e-6a3e-4e9a-9c9a-2f9b9a6a6b1a
Content-Type: application/json

{ "amount": 5000, "currency": "USD" }

// إعادة نفس الطلب بنفس المفتاح بسبب انقطاع الشبكة
// → الخادم يعيد نتيجة العملية الأولى بدل تنفيذها مجددًا

أهم النقاط

العنصر	الوظيفة
مفتاح فريد لكل عملية	يولّده العميل، عادة UUID، ولا يُعاد استخدامه لعملية مختلفة
تخزين مؤقت للنتيجة	الخادم يحفظ نتيجة أول تنفيذ ليعيدها عند التكرار
409 عند التعارض	إن وصل طلب بنفس المفتاح بينما الطلب الأول ما زال قيد التنفيذ

💡 نصائح عملية

استخدمها في أي عملية POST باهظة أو حسّاسة للتكرار: دفع، إرسال بريد، إنشاء طلب شراء
حدِّد مدة صلاحية لتخزين المفاتيح (مثلًا 24 ساعة) ووثّقها للمستهلكين

⚠️ أخطاء شائعة

توليد مفتاح جديد في كل محاولة إعادة إرسال بدل إعادة استخدام نفس المفتاح — يُبطل الغرض كاملًا
قبول نفس المفتاح مع جسم طلب مختلف دون رفض الطلب — يفتح الباب لتضارب في البيانات

🎓 تريد فهم الصورة الكاملة خطوة بخطوة؟ ابدأ من مسار REST-API الكامل بالعربي.

📚 للتعمق التقني الكامل بالإنجليزية: MDN Web Docs