POST
طريقة POST POST
POST ترسل بيانات لإنشاء مورد جديد أو تنفيذ عملية على الخادم، وهي غير آمنة وغير عديمة الأثر التراكمي.
POST تُستخدم غالبًا لإنشاء مورد جديد ضمن مجموعة (collection)، مثل إضافة مستخدم جديد لقائمة `/users`. حسب RFC 9110 فهي الطريقة "العامة" التي تُنفّذ أي معالجة يحدّدها المورد نفسه — إنشاء، إرسال نموذج، أو حتى تشغيل عملية معقّدة لا تناسبها بقية الطرق.
POST ليست آمنة (قد تُغيّر البيانات) وليست عديمة الأثر التراكمي: إرسال نفس طلب POST مرتين ينشئ سجلّين منفصلين عادة، ما لم يضِف المطوّر آلية حماية إضافية مثل مفتاح Idempotency-Key.
الصياغة
POST /resource
Content-Type: application/json
{ ...بيانات المورد الجديد }📄 مثال
POST /api/articles HTTP/1.1
Content-Type: application/json
{ "title": "مقال جديد" }
// الاستجابة
HTTP/1.1 201 Created
Location: /api/articles/43
{ "id": 43, "title": "مقال جديد" }أهم النقاط
| العنصر | الوظيفة |
|---|---|
| غير آمنة | تُنشئ بيانات أو تُشغّل معالجة على الخادم |
| غير عديمة الأثر التراكمي | تكرار نفس الطلب ينشئ سجلات متعددة ما لم تُضَف حماية يدويًا |
| 201 عند الإنشاء | الرد المتعارف عليه لإنشاء ناجح، مع ترويسة Location لرابط المورد الجديد |
💡 نصائح عملية
- أعد 201 Created مع ترويسة Location لا 200 عند إنشاء مورد جديد
- لعمليات POST الحساسة للتكرار (كالدفع)، استخدم ترويسة Idempotency-Key
⚠️ أخطاء شائعة
- استخدام POST لكل شيء (بما فيها القراءة والحذف) بدل الطريقة المناسبة — يفقد الواجهة اتساقها
- عدم التعامل مع طلبات POST المكرَّرة الناتجة عن ضعف الشبكة أو نقر مزدوج من المستخدم
خصائص ذات صلة
🎓 تريد فهم الصورة الكاملة خطوة بخطوة؟ ابدأ من مسار REST-API الكامل بالعربي.
📚 للتعمق التقني الكامل بالإنجليزية: MDN Web Docs