معرفی و ساختار

DorAPI سیستم استاندارد Doravel برای مدیریت و ساخت API های داینامیک و فیلترپذیر است.
این ساختار به شما کمک می‌کند بدون نیاز به تعریف دستی کوئری‌ها، داده‌ها را به‌صورت کاملاً انعطاف‌پذیر از طریق پارامترهای Query کنترل کنید.

---

پارامترهای کوئری (Query Parameters)

در DorAPI شما می‌توانید با استفاده از پارامترهای زیر رفتار پاسخ API را مشخص کنید:

• fields
• populate
• filters
• sort
• pagination

---

Fields

پارامتر fields مشابه عبارت SELECT در SQL عمل می‌کند و تعیین می‌کند چه فیلدهایی از مدل در خروجی ارسال شوند.

ساختار کلی

fields[index] = database_column

مثال‌ها

دریافت تمام فیلدها

?fields=*

نکته

اگر این پارامتر ارسال نشود، فیلدهای پیش‌فرض مدل (که در هر endpoint مستند می‌شوند) بازگردانده می‌شود.

دریافت فیلدهای خاص

?fields[0]=name

خروجی شامل id و name خواهد بود.

اطلاع

فیلد id همیشه به‌صورت خودکار اضافه می‌شود.

---

Populate

پارامتر populate برای افزودن روابط (Relations) مدل در پاسخ استفاده می‌شود. این ویژگی شبیه به ()with در Laravel است.

ساختار کلی

populate[index] = relation_name

مثال‌ها

دریافت تمام روابط

?populate=*

دریافت رابطه city

?populate[0]=city

انتخاب فیلدهای روابط (Populate با فیلدها)

DorAPI اجازه می‌دهد هنگام استفاده از populate تنها فیلدهای خاص یک relation را بازگردانید. این کار با ساختار زیر انجام می‌شود:

populate[relation_name][fields][index] = database_column

دریافت رابطه city با فیلدهای خاص

?populate[city][fields][0]=name
?populate[city][fields][1]=zip_code

اطلاع

در این مثال، تنها فیلدهای name و zip_code از رابطه city بازگردانده می‌شوند.

نکات تکمیلی

• اگر برای یک رابطه fields مشخص نکنید، مقدار پیش‌فرض یا defaultFields مربوط به آن relation اعمال می‌شود.
• برای جلوگیری از افشای اطلاعات حساس، همواره فهرست فیلدها و روابط مجاز را در allowedFields و allowedPopulates تنظیم کنید.
• در برخی کلاینت‌ها ممکن است لازم باشد براکت‌ها ([ ]) را در URL کدگذاری (URL-encode) کنید؛ اما اکثر فریم‌ورک‌ها و کتابخانه‌ها این ساختار را به‌صورت خودکار مدیریت می‌کنند.

---

Filters

پارامتر filters مانند متد where در SQL عمل می‌کند و برای فیلتر کردن نتایج استفاده می‌شود.

ساختار کلی

filters[column_name][behavior_operator]=value

برای استفاده از اپراتورهای منطقی AND و OR، می‌توانید از ساختارهای زیر استفاده کنید:

filters[$and][index][column_name][behavior_operator]=value
filters[$or][column_name][behavior_operator]=value

---

اپراتورهای منطقی (Logical Operators)

DorAPI از اپراتورهای منطقی $and و $or برای ترکیب چندین شرط فیلتر پشتیبانی می‌کند.

اپراتور	معادل SQL	توضیح
$and	AND	تمام شرایط باید برقرار باشند
$or	OR	حداقل یکی از شرایط باید برقرار باشد

نکته

به طور پیش‌فرض اگر اپراتور منطقی مشخص نکنید، از $and استفاده می‌شود.

ساختار با ایندکس‌های عددی

می‌توانید از ایندکس‌های عددی برای تعریف چندین شرط $and استفاده کنید:

filters[$and][0][column_name][behavior_operator]=value
filters[$and][1][column_name][behavior_operator]=value

ساختار با کلید فیلد مستقیم

همچنین می‌توانید مستقیماً از نام فیلد به عنوان کلید استفاده کنید:

filters[$and][column_name][behavior_operator]=value
filters[$or][column_name][behavior_operator]=value

---

اپراتورهای رفتاری (Behavior Operators)

اپراتور	توضیح	معادل SQL
eq$	برابر با	=
ne$	نابرابر با	=!
lt$	کمتر از	<
lte$	کمتر یا مساوی	=<
gt$	بیشتر از	>
gte$	بیشتر یا مساوی	=>
contains$	شامل (LIKE)	LIKE
in$	شامل در مجموعه	IN
notIn$	خارج از مجموعه	NOT IN
null$	مقدار تهی	IS NULL
notNull$	مقدار غیر تهی	IS NOT NULL

---

مثال‌های کاربردی

فیلتر بر اساس نام برابر با 'ali' و نام نابرابر با '1000'

filters[name][$eq]=ali
filters[name][$ne]=1000

فیلتر بر اساس نام‌های موجود در مجموعه

filters[last_name][$in][0]=mohammadi
filters[last_name][$in][1]=asadi

فیلتر با شرایط AND با ایندکس‌های عددی

filters[$and][0][is_active][$eq]=1
filters[$and][1][can_show][$eq]=1

این مثال معادل SQL زیر است:

WHERE is_active = 1 AND can_show = 1

فیلتر با شرایط OR با کلید فیلد مستقیم

filters[$or][id][$eq]=123
filters[$or][email][$eq]=test@example.com

این مثال معادل SQL زیر است:

WHERE id = 123 OR email = 'test@example.com'

ترکیب فیلترهای AND و OR

filters[$and][0][is_active][$eq]=1
filters[$and][1][can_show][$eq]=1
filters[$or][id][$eq]=123

این مثال معادل SQL زیر است:

WHERE (is_active = 1 AND can_show = 1) OR id = 123

ترکیب فیلترهای AND و OR

filters[$and][0][is_active][$eq]=1
filters[$and][1][can_show][$eq]=1
filters[$or][0][id][$eq]=123
filters[$or][1][id][$eq]=124

این مثال معادل SQL زیر است:

WHERE (is_active = 1 AND can_show = 1) OR (id = 123 OR id = 124)

ترکیب فیلترهای AND و OR

filters[$and][is_active][$eq]=1
filters[$or][id][$eq]=123

این مثال معادل SQL زیر است:

WHERE is_active = 1 OR id = 123

نکات تکمیلی

• می‌توانید از هر دو ساختار (ایندکس‌های عددی و کلید فیلد مستقیم) به صورت ترکیبی استفاده کنید.
• تمام فیلترهایی که اپراتور منطقی ندارند، به صورت پیش‌فرض با $and ترکیب می‌شوند.
• برای فیلترهای $or، تمام شرایط در یک گروه OR قرار می‌گیرند.

Filters در Meta Response

DorAPI علاوه بر اعمال فیلترها روی Query، اطلاعات فیلترهای فعال را نیز در بخش meta پاسخ API برمی‌گرداند.

این کار برای این است که کلاینت (Frontend) بتواند وضعیت فیلترهای اعمال‌شده را نمایش دهد یا مدیریت کند.

ساختار خروجی

{
  "code": 1,
  "message": null,
  "data": [
    {
      "id": 1,
      "name": "ساری",
      "is_active": true,
      "province_id": 1,
      "province_name": "مازندران",
      "province": {
        "id": 1,
        "name": "مازندران"
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 2
    },
    "filters": [
      {
        "key": "is_active",
        "value": true,
        "operator": "$eq",
        "label": "فعال"
      }
    ]
  }
}

بخش	توضیح
filters	لیست فیلترهای فعال
key	نام فیلد
value	مقدار فیلتر
operator	نوع شرط
label	مقدار قابل نمایش

نکات تکمیلی

• اگر چند مقدار (مثل $in) استفاده شود، هر مقدار جداگانه در meta ثبت می‌شود
• این داده‌ها فقط informational هستند و روی Query تأثیر ندارند (read-only metadata)

---

Sort

پارامتر sort برای مرتب‌سازی نتایج استفاده می‌شود.

ساختار کلی

sort[index] = column_name:order

مثال‌ها

مرتب‌سازی بر اساس تاریخ به‌روزرسانی نزولی

sort[0]=updated_at:desc

مرتب‌سازی بر اساس تاریخ ایجاد صعودی

sort[0]=created_at:asc

نکات تکمیلی

• اگر order مشخص نشود، به‌صورت پیش‌فرض asc (صعودی) در نظر گرفته می‌شود.
• می‌توانید چندین معیار مرتب‌سازی را به‌صورت ترکیبی استفاده کنید.

مرتب‌سازی با Relation

برای استفاده از این ویژگی، در کلاس DorApi باید متد sorts را با افزودن رابطه (relation) و فیلد مربوطه تنظیم کنید. درخواست‌ها باید با ساختاری مشابه sort=relation_name.column_name:desc ارسال شوند.

در حال حاضر، این قابلیت برای روابط belongsTo و hasOne پشتیبانی می‌شود.

به عنوان مثال، برای مرتب‌سازی شهرستان‌ها بر اساس نام استان در کلاس CityDorapi، می‌توانید روابط زیر را تعریف کنید:

مرتب سازی همراه با relation

sort[0]=province.name:desc

رفتار meta در response

DorAPI اطلاعات sort های اعمال‌شده را در meta برمی‌گرداند:

مثال کامل:

GET /api/cities?sort[0]=province.name:asc&sort[1]=created_at:desc

رفتار meta در response

DorAPI اطلاعات sort های اعمال‌شده را در meta برمی‌گرداند:

"meta": {
    "code": 1,
    "message": null,
    "data": [...],
    "sorts": [
        {
          "key": "province.name",
          "order": "asc"
        },
        {
            "key": "created_at",
            "order": "desc"
        }
    ]
}

جمع‌بندی

نوع Sort	مثال
ساده	sort[0]=name:asc
relation	sort[0]=province.name:asc
چندگانه	sort[0]=name:asc&sort[1]=created_at:desc

---

Pagination

پارامتر pagination برای کنترل صفحه‌بندی نتایج استفاده می‌شود. در DorAPI دو روش مختلف برای صفحه‌بندی وجود دارد:

صفحه‌بندی بر اساس Offset (شماره شروع)

در این روش، شما موقعیت شروع و تعداد آیتم‌های مورد نظر را مشخص می‌کنید.

ساختار کلی

pagination[start] = start_position
pagination[limit] = items_count

مثال‌ها

دریافت آیتم‌ها از موقعیت 2 با حد 3

?pagination[start]=2&pagination[limit]=3

اطلاع

• start: موقعیت شروع (از 0 شروع می‌شود)
• limit: تعداد آیتم‌های بازگردانده شده

ساختار پاسخ

{
  "code": 1,
  "message": null,
  "data": [...],
  "meta": {
    "pagination": {
      "start": 2,
      "limit": 3
    }
  }
}

---

صفحه‌بندی بر اساس Page (شماره صفحه)

در این روش، شما شماره صفحه و تعداد آیتم‌های هر صفحه را مشخص می‌کنید.

ساختار کلی

pagination[page] = page_number
pagination[pageSize] = items_per_page

مثال‌ها

دریافت صفحه 2 با 5 آیتم در هر صفحه

?pagination[page]=2&pagination[pageSize]=5

اطلاع

• page: شماره صفحه (از 1 شروع می‌شود)
• pageSize: تعداد آیتم‌های هر صفحه

ساختار پاسخ

{
  "code": 1,
  "message": null,
  "data": [...],
  "meta": {
    "pagination": {
      "page": 2,
      "pageSize": 5
    }
  }
}

---

دریافت تعداد کل (Total Count)

برای دریافت اطلاعات تکمیلی صفحه‌بندی از جمله تعداد کل آیتم‌ها و تعداد صفحات، می‌توانید پارامتر pagination[withCount] را استفاده کنید.

ساختار کلی

pagination[withCount] = 1

مثال‌ها

دریافت تعداد کل آیتم‌ها

?pagination[withCount]=1

ترکیب با صفحه‌بندی بر اساس صفحه

?pagination[page]=1&pagination[pageSize]=15&pagination[withCount]=1

ساختار پاسخ

{
  "code": 1,
  "message": null,
  "data": [...],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 15,
      "pageCount": 1,
      "total": 9
    }
  }
}

اطلاع

هنگامی که withCount=1 فعال باشد، پاسخ شامل فیلدهای زیر می‌شود:

• total: تعداد کل آیتم‌ها
• pageCount: تعداد کل صفحات

---

نکات تکمیلی Pagination

نکته

• اگر هیچ پارامتر pagination ارسال نشود، مقادیر پیش‌فرض اعمال می‌شوند (معمولاً صفحه 1 با اندازه صفحه پیش‌فرض).
• نمیتوانید pagination[page] و pagination[pageSize] را همزمان با pagination[start] و pagination[limit] استفاده کنید.
• پارامتر pagination[withCount] را می‌توانید با هر دو روش صفحه‌بندی ترکیب کنید.
• اطلاعات صفحه‌بندی در بخش meta.pagination پاسخ برگردانده می‌شود.

---

جمع‌بندی

پارامتر	توضیح
fields	انتخاب فیلدهای خاص از خروجی
populate	اضافه کردن روابط مدل
filters	فیلتر کردن نتایج با اپراتورهای منطقی
sort	مرتب‌سازی داده‌ها
pagination	صفحه‌بندی نتایج

---

نکات پایانی

• در تمام endpoint های DorAPI، می‌توانید چندین پارامتر از هر نوع را به صورت ترکیبی استفاده کنید.
• فیلترها، فیلدها و روابط همگی با هم قابل استفاده هستند.
• ساختار DorAPI به صورت ماژولار پیاده‌سازی شده تا با مدل‌های Doravel کاملاً سازگار باشد.

اخطار

توصیه می‌شود برای endpoint ها، فیلدهای مجاز (allowedFields) و روابط مجاز (allowedPopulates) را در تنظیمات DorAPI مشخص کنید تا از افشای اطلاعات حساس جلوگیری شود.