Api Design

لكل شاشة من Figma، حلل الـ UI واستخرج الـ services المطلوبة بالقواعد دي:

Rule 1: Multi-Section Screen → Separate Service Per Section

شاشة فيها: Banners + Categories + Products
    ↓
GET /banners          ← service 1
GET /categories       ← service 2
GET /products         ← service 3

❌ FORBIDDEN: GET /home-data (كل حاجة في service واحدة)

استثناء: ممكن يكون عند الباك اند endpoint واحد زي GET /home بيرجع كل الـ sections مع بعض — ده مقبول لو الباك اند قرر كده.

Rule 2: List Screens → Pagination Required

أي شاشة فيها list
    ↓
GET /resource?page=1&per_page=15
    ↓
Response يشمل: data[] + meta object

Rule 3: Multi-Step Forms → Validate Per Step + Final Create

فورم على 3 صفحات:
    ↓
POST /resource/validate-step-1    ← validates page 1 fields
POST /resource/validate-step-2    ← validates page 2 fields
POST /resource/validate-step-3    ← validates page 3 fields
POST /resource                    ← final create (all data)

Rule 4: File Uploads → Inline with Form-Data

الفايلات تتبعت inline مع باقي الداتا في نفس الـ request عبر form-data.

POST /api/v1/{app}/resource
Content-Type: multipart/form-data

Fields:
  name: "..."
  email: "..."
  image: [FILE]              ← single file
  images[]: [FILE, FILE]     ← multiple files (array notation)

✅ CORRECT: فايل + داتا في نفس الـ request (form-data)

قواعد رفع الملفات:

• Accepted formats: jpeg, jpg, png, pdf
• Max size: 5MB (5120 KB) per file
• Single file: field name عادي (e.g., image, cover_image, logo)
• Multiple files: array notation images[]
• File + text: كلهم في نفس الـ form-data body

Rule 5: CRUD Operations → 5 Standard Services

GET    /api/v1/{app}/resource              ← list (paginated)
GET    /api/v1/{app}/resource/{id}         ← detail
POST   /api/v1/{app}/resource              ← create
PUT    /api/v1/{app}/resource/{id}         ← update
DELETE /api/v1/{app}/resource/{id}         ← delete

Rule 6: Toggle/Switch Endpoints

أي زرار toggle (تفعيل/إلغاء تفعيل) → PUT بدون body

PUT /api/v1/{app}/switch-{field-name}
PUT /api/v1/{app}/resource/{id}/switch-{field-name}

Response: { "status": "success", "code": 200, "message": "..." }

Rule 7: Status Change Endpoints

أي تغيير حالة → PUT مع الـ status في الـ URL

PUT /api/v1/{app}/resource/{id}/change-status-to-{new_status}
PUT /api/v1/{app}/resource/{id}/accept
PUT /api/v1/{app}/resource/{id}/reject

Response: { "status": "success", "code": 200, "message": "..." }

Rule 8: Unified Entities (CRITICAL)

الـ Entity واحدة في كل مكان. الـ entity في list = نفسها في detail = نفسها جوا parent entity.

// ❌ FORBIDDEN: Different response shapes for same entity

Step 2: Endpoint Naming Convention

URL Structure

{{base_url}}/api/v1/{app}/{resource}                    ← list/create
{{base_url}}/api/v1/{app}/{resource}/{id}               ← detail/update/delete
{{base_url}}/api/v1/{app}/{resource}/{id}/{action}      ← custom action on item
{{base_url}}/api/v1/{app}/{resource}/{action}            ← custom action on resource
{{base_url}}/api/v1/{resource}                           ← shared/public endpoints