ETag

ترويسة ETag والطلبات الشرطية ETag

ETag معرّف فريد لنسخة معيّنة من مورد، يسمح للعميل بالتحقق إن كان المورد تغيّر دون تحميله كاملًا مجددًا.

الخادم يرفق ترويسة ETag (Entity Tag) بردّه — قيمة نصية معتمة تمثّل "بصمة" الحالة الحالية للمورد. في الطلب التالي، يرسل العميل هذه القيمة ضمن ترويسة If-None-Match. إن لم تتغيّر البصمة، يردّ الخادم بـ 304 Not Modified بلا جسم، فيوفّر نطاقًا ترددياً؛ وإن تغيّرت، يعيد المورد الكامل مع 200 وETag جديد.

نفس الآلية تُستخدم بشكل معاكس لمنع التعارض عند الكتابة: يرسل العميل If-Match مع ETag الذي قرأه قبل تعديل مورد، فإن كان قد تغيّر بواسطة مستخدم آخر في الأثناء، يرفض الخادم الطلب بـ 412 Precondition Failed بدل الكتابة فوق تعديل الآخر (Optimistic Concurrency Control).

الصياغة

// الاستجابة
ETag: "abc123"

// الطلب التالي للقراءة
If-None-Match: "abc123"

// الطلب للكتابة الآمنة من التعارض
If-Match: "abc123"

📄 مثال

// أول طلب
GET /api/articles/42
→ 200 OK, ETag: "v1-8f3"

// طلب لاحق من نفس العميل
GET /api/articles/42
If-None-Match: "v1-8f3"
→ 304 Not Modified (بلا جسم — لم يتغيّر شيء)

أهم النقاط

العنصر	الوظيفة
If-None-Match	يُرسَل مع GET للتحقق قبل إعادة تحميل مورد لم يتغيّر
If-Match	يُرسَل مع PUT/PATCH/DELETE لمنع الكتابة فوق تعديل حدث في الأثناء
304 Not Modified	رد الخادم عندما تتطابق البصمة — يوفّر النطاق الترددي

💡 نصائح عملية

ولّد ETag من تجزئة (hash) محتوى المورد أو من حقل تحديث داخلي — لا تعتمد فقط على الوقت لتفادي تطابقات زائفة
استخدم If-Match مع عمليات التعديل الحرجة (مثل تعديل مستند يشترك فيه عدة مستخدمين) لتفادي فقدان تعديلات

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

توليد ETag جديد بشكل عشوائي كل مرة حتى لو لم يتغيّر المورد — يُبطل فائدة الآلية كاملة
الاعتماد على ETag وحده للأمان بدل المصادقة — الغرض هو التحقق من الحالة لا حماية الوصول

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

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