PUT

طريقة PUT PUT

PUT تستبدل مورداً بالكامل بالتمثيل المُرسَل، وهي عديمة الأثر التراكمي رغم أنها تُغيّر البيانات.

PUT تطلب من الخادم تخزين التمثيل المرفق تحت رابط (URI) محدَّد، فيستبدل المورد الحالي بالكامل — أو ينشئه إن لم يكن موجودًا ورابطه معروفًا مسبقًا (خلافًا لـ POST التي تنشئ الرابط على الخادم). أي حقل لا يُرسَل ضمن الجسم يُعتبر عادة غير موجود بعد التنفيذ.

رغم أن PUT تُغيّر حالة الخادم، فهي عديمة الأثر التراكمي حسب RFC 9110: تكرار نفس الطلب عدة مرات يترك المورد بنفس الحالة النهائية، بخلاف POST.

الصياغة

PUT /resource/:id
Content-Type: application/json

{ ...التمثيل الكامل للمورد }

📄 مثال

PUT /api/articles/42 HTTP/1.1
Content-Type: application/json

{ "title": "عنوان محدَّث", "body": "محتوى كامل" }

// الاستجابة
HTTP/1.1 200 OK

{ "id": 42, "title": "عنوان محدَّث", "body": "محتوى كامل" }

أهم النقاط

العنصر	الوظيفة
استبدال كامل	الحقول غير المُرسَلة تُفقد أو تعود لقيمتها الافتراضية
عديمة الأثر التراكمي	التكرار لا يغيّر النتيجة النهائية رغم أنها طريقة غير آمنة
رابط معروف مسبقًا	العميل يحدّد رابط المورد، بخلاف POST حيث الخادم يولّده

💡 نصائح عملية

استخدم PUT عندما يملك العميل التمثيل الكامل للمورد وينوي استبداله بالكامل
استخدم PATCH بدلًا منه عند إرسال حقل واحد أو جزء صغير فقط

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

إرسال جسم جزئي مع PUT بتوقّع أن الحقول الغائبة تبقى كما هي — هذا سلوك PATCH لا PUT
استخدام PUT لإنشاء موارد جديدة يولّد الخادم معرّفها — هذا دور POST

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

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