REST APIs

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	خطأ في الخادم

شكل الأخطاء

أعد بنية ثابتة يفهمها العميل:

{ "error": { "code": "VALIDATION", "message": "البريد غير صالح", "field": "email" } }

الترقيم

للقوائم الكبيرة استخدم الترقيم بالمؤشر (cursor) بدل الإزاحة (offset) لثبات النتائج وسرعتها:

GET /posts?limit=20&cursor=eyJpZCI6NDJ9

أخطاء شائعة

• إرجاع 200 مع رسالة خطأ في المحتوى.
• تنفيذ تغييرات عبر GET (قد تُستدعى من الروابط المسبقة أو برامج الزحف).
• كشف تفاصيل داخلية (تتبع الأخطاء، استعلامات SQL) في رسائل الخطأ.