سجل التعديلات

الفرق مقارنةً بالنسخة السابقة

+ **REST** أسلوب لتصميم الواجهات البرمجية فوق HTTP: كل شيء **مورد** له عنوان (URL)، والعمليات عليه تُعبَّر عنها بأفعال HTTP القياسية.
  
+ ## الموارد والأفعال
+ 
+ | الطلب | المعنى |
+ |---|---|
+ | `GET /posts` | قائمة المنشورات |
+ | `GET /posts/42` | منشور واحد |
+ | `POST /posts` | إنشاء منشور |
+ | `PATCH /posts/42` | تعديل جزئي |
+ | `PUT /posts/42` | استبدال كامل |
+ | `DELETE /posts/42` | حذف |
+ 
+ استخدم أسماء (posts) لا أفعالاً (getPosts) في المسارات.
+ 
+ - `GET` آمن: لا يغيّر شيئاً على الخادم.
+ - `GET` و`PUT` و`DELETE` **متساوية الأثر** (idempotent): تكرار الطلب نفسه يترك الحالة نفسها.
+ - `POST` ليس كذلك، ولهذا تُستخدم أحياناً ترويسة `Idempotency-Key` لمنع التكرار عند إعادة المحاولة.
+ 
+ ## رموز الحالة
+ 
+ | الرمز | متى |
+ |---|---|
+ | `200 OK` | نجاح مع محتوى |
+ | `201 Created` | أُنشئ مورد (مع ترويسة `Location`) |
+ | `204 No Content` | نجاح بلا محتوى |
+ | `400 Bad Request` | مدخلات غير صالحة |
+ | `401 Unauthorized` | غير مصادَق (لم يسجل الدخول) |
+ | `403 Forbidden` | مصادَق لكن بلا صلاحية |
+ | `404 Not Found` | المورد غير موجود |
+ | `409 Conflict` | تعارض مع الحالة الحالية |
+ | `429 Too Many Requests` | تجاوز حد الطلبات |
+ | `500 Internal Server Error` | خطأ في الخادم |
+ 
+ ## شكل الأخطاء
+ 
+ أعد بنية ثابتة يفهمها العميل:
+ 
+ ```json
+ { "error": { "code": "VALIDATION", "message": "البريد غير صالح", "field": "email" } }
+ ```
+ 
+ ## الترقيم
+ 
+ للقوائم الكبيرة استخدم الترقيم بالمؤشر (cursor) بدل الإزاحة (offset) لثبات النتائج وسرعتها:
+ 
+ ```
+ GET /posts?limit=20&cursor=eyJpZCI6NDJ9
+ ```
+ 
+ ## أخطاء شائعة
+ 
+ - إرجاع `200` مع رسالة خطأ في المحتوى.
+ - تنفيذ تغييرات عبر `GET` (قد تُستدعى من الروابط المسبقة أو برامج الزحف).
+ - كشف تفاصيل داخلية (تتبع الأخطاء، استعلامات SQL) في رسائل الخطأ.