أساسيات REST API: Resources و Endpoints و HTTP Methods و Status Codes

في الجزء اللي فات من السلسلة فهمنا الصورة الكبيرة لـ REST API: بيعمل إيه وليه أصلًا بنحتاجه. لو فاتك الجزء الأول، أنصحك تبدأ به من هنا: ما هي REST API؟ فهم الفكرة بالمثال خطوة بخطوة .

في المقال الحالي هننزل مستوى أعمق ونتكلم عن اللبنات الأساسية لأي REST API محترم: Resources، Endpoints، HTTP Methods، و HTTP Status Codes، مع أمثلة عملية تقدر تربطها مباشرة بشغلك اليومي.

ما هو Resource في REST API؟

في REST، إحنا بنفكر في البيانات كـ Resources مش كجداول في قاعدة البيانات بس. الــ Resource هو كيان منطقي في السيستم بتاعك، زي User، Post، Product، Order... إلخ.

نفس الـ Resource ممكن يكون متخزّن في أكتر من جدول أو حتى في Service خارجية، لكن من ناحية الـ API هو ظاهر ككيان واحد باسم واضح زي users أو orders. الفكرة إن العميل يتعامل مع أسماء منطقية، مش مع تفاصيل الـ Database الداخلية.

• مثال: نظام متجر إلكتروني ممكن يبقى فيه Resources زي: products, categories, orders, customers.
• المهم إن كل Resource يمثل مفهوم واضح في الدومين بتاعك، بغض النظر عن شكل التخزين.

لما تفكر بعقلية Resources، تصميم الـ API بيبقى أوضح وأسهل في التوسعة، وبيساعد الفريق كله يتكلم نفس اللغة.

ما هو Endpoint؟ وكيف نصمّم URI واضح ومعبر؟

Endpoint هو عنوان الـ URL اللي العميل بيضربه عشان يتعامل مع Resource معيّن، مع HTTP Method معيّن (GET, POST, إلخ). يعني العنوان + نوع الطلب مع بعض هما اللي بيحددوا العملية.

مثلًا، لو عندك Resource اسمه users، ممكن يكون عندك Endpoints بالشكل ده:

• GET /api/users → رجّعلي قائمة المستخدمين.
• GET /api/users/5 → رجّعلي المستخدم رقم 5.
• POST /api/users → أضف مستخدم جديد.
• PUT /api/users/5 → عدّل بيانات المستخدم رقم 5 بالكامل.
• DELETE /api/users/5 → احذف المستخدم رقم 5.

قواعد عملية لتصميم URIs نظيفة

• استخدم أسماء (Nouns) مش أفعال: صح /api/users، غلط /api/getUsers.
• خلي الأسماء في الغالب بالجمع: users, posts, products.
• حط الـ ID جوه الـ path: /api/users/5 بدل ما يكون في Query String.
• استخدم Nested URIs فقط لما تكون العلاقة واضحة جدًا: زي /api/posts/10/comments للكومنتس الخاصة ببّوست معيّن.

الهدف إن أي مطوّر أول مرة يشوف الـ Endpoint يقدر يتوقع بيعمل إيه من غير ما يقرأ Documentation طويلة.

HTTP Methods الأساسية في REST API

REST بيستغل الـ HTTP Methods اللي أصلا موجودة في البروتوكول، ويربطها بعمليات CRUD (Create, Read, Update, Delete) على الـ Resources.

GET

GET بيستخدم للقراءة فقط من غير أي تعديل على الداتا. مثال: GET /api/posts عشان ترجع قائمة البوستات، أو GET /api/posts/10 عشان ترجع بوست واحد.

من خصائص GET إنه Safe و Idempotent، يعني تكرار نفس الطلب مش هيغيّر حالة السيرفر، بس كل مرة هترجع نفس النتيجة (لو الداتا ما اتغيرتش).

POST

POST غالبًا بيستخدم لإنشاء Resource جديد أو لتنفيذ عملية مش متكررة بنفس النتيجة. مثلًا: POST /api/posts مع JSON في الـ body عشان تضيف بوست جديد.

لو بعت نفس طلب POST مرتين بنفس البيانات، وارد جدًا يتخلق بوستين مختلفين، علشان كده POST مش Idempotent بطبيعته.

PUT

PUT بيُستخدم عادةً للاستبدال الكامل للـ Resource (أو لإنشائه لو مش موجود حسب التصميم). مثال: PUT /api/posts/10 عشان تعدّل البوست رقم 10 بكل تفاصيله.

PUT Idempotent: لو نفّذت نفس الطلب عشر مرات بنفس الـ body، الحالة النهائية على السيرفر هتكون واحدة.

PATCH

PATCH مخصص للتعديل الجزئي على الـ Resource. مثال: PATCH /api/posts/10 مع body فيه {"title": "New Title"} بس.

من الناحية النظرية PATCH مش لازم يكون Idempotent، لكن تقدر تصمّمه في الـ API بتاعك بحيث يكون التعديل المحدد دايمًا بيؤدي لنفس النتيجة لو اتكرّر بنفس الـ body.

DELETE

DELETE بيستخدم لحذف Resource موجود. مثلًا: DELETE /api/posts/10 عشان تحذف البوست رقم 10 من النظام.

المفروض إن DELETE يكون Idempotent: أول طلب بيحذف الـ Resource، وأي طلبات بعد كده لنفس الـ ID مش هتغيّر حاجة في حالة السيرفر.

مفهوم Idempotent والفرق بين PUT و PATCH

Idempotent يعني لو نفّذت نفس العملية بنفس البيانات أكثر من مرة متتالية، النتيجة النهائية على السيرفر تفضل هي هي بعد أول مرة.

• GET: Idempotent (قراءة فقط).
• PUT: Idempotent (استبدال كامل بنفس القيمة).
• DELETE: Idempotent (بعد أول Delete الـ Resource بيختفي وخلاص).
• POST: مش Idempotent (كل مرة ممكن تضيف Resource جديد).
• PATCH: يعتمد على نوع التعديل وكيفية تطبيقه في الـ API.

الفرق العملي بين PUT و PATCH:

• PUT غالبًا يعني: ابعتلي الـ Resource كامل، وأنا هاستبدله باللي عندي.
• PATCH يعني: ابعتلي بس الحقول اللي عايز تغيّرها، وأنا هعدّلها جوه الـ Resource الموجود.

أهم HTTP Status Codes في REST APIs

الــ HTTP Status Code هو الرقم اللي بيطلع في بداية الـ Response، وبيقول للعميل النتيجة العامة للطلب: نجح؟ فيه خطأ من عندك؟ ولا حصلت مشكلة في السيرفر؟

أكواد النجاح (2xx)

• 200 OK → الطلب نجح وفيه Body (مثال: GET ناجح أو PUT ناجح).
• 201 Created → تم إنشاء Resource جديد (غالبًا مع POST)، ويفضّل ترجع بياناته في الـ body.
• 204 No Content → الطلب نجح بس مفيش محتوى راجع (مثال: DELETE ناجح).

أكواد خطأ من العميل (4xx)

• 400 Bad Request → الطلب نفسه مش مظبوط (JSON مكسور، باراميتر ناقص، إلخ).
• 401 Unauthorized → مفيش Authentication صحيحة (توكن ناقص أو غلط).
• 403 Forbidden → متوثّق بس مش مسموح لك بالعملية دي (مشكلة Authorization).
• 404 Not Found → الـ Resource المطلوب مش موجود.
• 409 Conflict → تعارض في الحالة (مثال: قيمة مكررة في حقل لازم يكون unique).
• 422 Unprocessable Entity → البيانات وصلت لكن Validation فشل.

أكواد خطأ من السيرفر (5xx)

• 500 Internal Server Error → خطأ غير متوقع في السيرفر.
• 502 / 503 / 504 → مشاكل في Gateway أو Service مش متاحة أو Timeout.

إزاي نختار Status Code المناسب؟

القاعدة الذهبية: اختار كود يعكس اللي حصل فعلًا، وكن ثابت في استخدامك ليه في كل الـ Endpoints.

• GET /api/posts/10
  موجود → 200 OK
  مش موجود → 404 Not Found
• POST /api/posts
  تم إنشاء بوست → 201 Created
  Validation فشل → 422 Unprocessable Entity مع تفاصيل الأخطاء في JSON
• PUT /api/posts/10
  عدّلت البوست بالكامل بنجاح → 200 OK أو 204 No Content
  الـ ID مش موجود → 404 Not Found
• DELETE /api/posts/10
  اتحذف أو كان محذوف أصلًا → 204 No Content
  مفيش صلاحية → 403 Forbidden

مثال عملي كامل لمورد posts

خلينا نجمّع كل الكلام ده في تصميم بسيط لمجموعة Endpoints لمورد posts:

• GET /api/posts → إرجاع كل البوستات (200 OK).
• GET /api/posts/{id} → إرجاع بوست واحد (200 OK أو 404 Not Found).
• POST /api/posts → إنشاء بوست جديد (201 Created أو 422 Unprocessable Entity).
• PUT /api/posts/{id} → استبدال البوست بالكامل (200/204 أو 404).
• PATCH /api/posts/{id} → تعديل جزئي (200/204 أو 404).
• DELETE /api/posts/{id} → حذف بوست (204 أو 403 لو مش مسموح).

مثال Response لإنشاء بوست جديد:

{
  "data": {
    "id": 10,
    "title": "Introduction to REST API Design",
    "body": "Content of the article...",
    "tags": ["rest", "api", "design"],
    "created_at": "2026-03-22T11:30:00Z"
  },
  "message": "Post created successfully"
}

بالتصميم ده، أي مطوّر يقدر يبص على قائمة الـ Endpoints ويفهم بسرعة كل عملية بتعمل إيه، وإيه الـ Status Codes المتوقعة منها، وده بالظبط اللي بنسعى له في أي REST API قوي وقابل للتوسع.