API- Pagination & Filtering

Pagination چیست؟

Pagination یعنی شکستن خروجی یک API به صفحه‌های کوچک‌تر، به‌جای اینکه همه‌ی داده‌ها یک‌جا برگردند.
مثلاً اگر سیستم ۱۰۰ هزار مشتری دارد، نباید همه را با یک GET /customers برگرداند؛ چون باعث کندی، فشار روی Database، مصرف زیاد Memory و افزایش Latency می‌شود.

چرا Pagination مهم است؟

در API Testing، Pagination فقط موضوع نمایش صفحه‌ای نیست؛ روی Performance، Data Consistency، User Experience و Correctness اثر دارد.
اگر درست پیاده‌سازی نشود ممکن است:

• بعضی رکوردها نمایش داده نشوند

• بعضی رکوردها تکراری برگردند

• ترتیب داده‌ها به‌هم بریزد

• در زمان اضافه/حذف شدن داده، خروجی صفحات ناپایدار شود

• API با حجم زیاد داده کند یا ناپایدار شود

Limit / Offset Pagination

Limit / Offset چیست؟

در این مدل، limit تعداد رکوردهای برگشتی را مشخص می‌کند و offset می‌گوید از چندمین رکورد به بعد داده برگردد.

مثال:

GET /customers?limit=10&offset=0

یعنی ۱۰ رکورد اول را برگردان.

GET /customers?limit=10&offset=10

یعنی ۱۰ رکورد بعدی را برگردان.

کاربرد Limit / Offset

این مدل ساده، قابل‌فهم و رایج است و برای لیست‌های کوچک یا متوسط خوب جواب می‌دهد.
مثلاً:

• لیست مشتریان

• لیست تراکنش‌ها

• لیست درخواست‌ها

• صفحات مدیریتی

ریسک‌های Limit / Offset

در دیتای بزرگ یا دیتایی که مرتب تغییر می‌کند، offset pagination ممکن است مشکل‌ساز شود.
مثلاً اگر بین صفحه اول و دوم یک رکورد جدید اضافه شود، ممکن است بعضی داده‌ها تکراری یا گم شوند.

از نظر Performance هم offsetهای بزرگ می‌توانند برای Database سنگین باشند.

Cursor-based Pagination

Cursor-based Pagination چیست؟

در این مدل به‌جای offset، از یک cursor استفاده می‌شود. Cursor معمولاً نشانه‌ای از آخرین رکورد دیده‌شده یا موقعیت فعلی در لیست است.

مثال:

GET /transactions?limit=20&cursor=eyJpZCI6MTAwMjN9

یعنی از جایی که این cursor مشخص می‌کند، ۲۰ رکورد بعدی را برگردان.

کاربرد Cursor-based Pagination

این مدل برای داده‌های بزرگ، real-time یا پرتغییر بهتر است.
مثلاً:

• تراکنش‌های بانکی

• لاگ‌ها

• پیام‌ها

• activity feed

• لیست‌هایی با حجم بالا

مزیت Cursor-based

• برای دیتای بزرگ بهتر از offset است

• احتمال رکورد تکراری یا گم‌شده کمتر می‌شود

• برای infinite scroll و داده‌های جدید مناسب‌تر است

• در سیستم‌های پرترافیک پایدارتر است

Filtering چیست؟

Filtering یعنی محدود کردن خروجی API بر اساس شرط‌های مشخص.

مثال:

GET /customers?status=ACTIVE&city=Tehran

یعنی فقط مشتریان فعال شهر تهران را برگردان.

یا:

GET /transactions?fromDate=2026-01-01&toDate=2026-01-31&status=SUCCESS

یعنی تراکنش‌های موفق در بازه تاریخی مشخص را برگردان.

نکات تستی مهم در Filtering

در تست Filtering فقط نباید ببینی API جواب می‌دهد؛ باید بررسی کنی خروجی واقعاً مطابق فیلتر است.

باید تست کنی:

• فیلتر معتبر

• فیلتر نامعتبر

• چند فیلتر هم‌زمان

• مقدار خالی

• مقدار خارج از دامنه

• case sensitivity

• فیلتر روی تاریخ

• فیلتر روی status

• فیلتر روی مقدار عددی

• ترکیب filter + pagination

Pagination + Filtering با هم

در APIهای واقعی، معمولاً Pagination و Filtering با هم استفاده می‌شوند.

مثال:

GET /customers?status=ACTIVE&city=Tehran&limit=20&offset=0

در تست باید مطمئن شوی:

• اول فیلتر درست اعمال شده

• بعد pagination روی نتیجه‌ی فیلترشده اعمال شده

• تعداد رکوردها از limit بیشتر نیست

• صفحه بعدی ادامه‌ی همان دیتای فیلترشده است

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

Sorting کنار Pagination

برای اینکه Pagination قابل اعتماد باشد، معمولاً باید Sorting مشخص داشته باشیم.

مثال:

GET /customers?limit=10&offset=0&sort=createdAt,desc

اگر sorting مشخص نباشد، خروجی صفحات ممکن است ناپایدار شود.
در تست حرفه‌ای باید بگویی pagination بدون sort پایدار، ریسک duplicate/missing records دارد.

Status Codeهای مهم

اگر پارامترهای pagination یا filtering نامعتبر باشند، معمولاً انتظار خطای 4xx داریم.

مثلاً:

• limit منفی

• offset منفی

• limit خیلی بزرگ

• date format نامعتبر

• status خارج از مقدارهای مجاز

پاسخ مناسب معمولاً 400 Bad Request یا طبق Contract است.

اهمیت این سرفصل برای Backend Tester

Backend Tester باید بتواند بررسی کند:

• limit و offset درست اعمال می‌شوند

• cursor درست تولید و مصرف می‌شود

• صفحه‌ها رکورد تکراری یا گم‌شده ندارند

• فیلترها دقیقاً روی داده اعمال می‌شوند

• ترکیب pagination + filtering + sorting درست کار می‌کند

• API در برابر پارامترهای نامعتبر خطای مناسب می‌دهد

• در حجم داده زیاد، رفتار API از نظر Performance قابل قبول است

نکته امتحانی مهم

در پاسخ امتحانی فقط نگویید:
Pagination یعنی صفحه‌بندی و Filtering یعنی فیلتر کردن.

پاسخ خوب باید این کلیدواژه‌ها را داشته باشد:
limit, offset, cursor, page size, next cursor, filter criteria, sorting, stable order, missing records, duplicate records, performance risk, 400 Bad Request, contract validation

نمونه پاسخ کامل کوتاه

Pagination در API یعنی تقسیم خروجی بزرگ به بخش‌های کوچک‌تر با روش‌هایی مثل limit/offset یا cursor-based pagination. در روش limit/offset تعداد رکورد و نقطه شروع مشخص می‌شود، اما در داده‌های بزرگ یا پرتغییر ممکن است باعث رکورد تکراری یا گم‌شده شود. در روش cursor-based، API با یک cursor ادامه‌ی لیست را مشخص می‌کند و برای داده‌های real-time یا حجیم پایدارتر است. Filtering یعنی محدود کردن خروجی بر اساس شرط‌هایی مثل status, date range یا customer type. در تست باید ترکیب pagination + filtering + sorting، پارامترهای نامعتبر، ترتیب ثابت داده‌ها و نبودن رکورد تکراری یا جاافتاده بررسی شود.

کلیدواژه‌ها

Pagination Filtering Limit Offset Cursor Cursor-based Pagination Page Size Next Cursor Previous Cursor Total Count Filter Criteria Sorting Stable Order Duplicate Records Missing Records Performance Risk 400 Bad Request Contract Validation

Pagination (تقسیم خروجی API به صفحه‌های کوچک‌تر): برای کنترل حجم response، بهبود performance و مدیریت لیست‌های بزرگ استفاده می‌شود.

Filtering (محدود کردن خروجی بر اساس شرط): برای جستجو و نمایش داده‌های مرتبط مثل مشتریان فعال یا تراکنش‌های یک بازه زمانی استفاده می‌شود.

Limit (تعداد رکوردهای برگشتی در هر درخواست): برای تعیین اندازه صفحه یا page size استفاده می‌شود.

Offset (تعداد رکوردهایی که باید از ابتدای نتیجه رد شوند): در مدل limit/offset pagination برای رفتن به صفحه‌های بعدی استفاده می‌شود.

Cursor (نشانه‌ی موقعیت فعلی در لیست داده): در cursor-based pagination برای گرفتن بخش بعدی داده استفاده می‌شود.

Cursor-based Pagination (صفحه‌بندی بر اساس cursor به‌جای offset): برای داده‌های بزرگ، پرتغییر و real-time مناسب‌تر است.

Page Size (تعداد آیتم‌های هر صفحه): معمولاً با limit مشخص می‌شود و باید حد مجاز داشته باشد.

Next Cursor (cursor برگشتی برای صفحه بعد): در response برگردانده می‌شود تا client بتواند ادامه داده را بگیرد.

Previous Cursor (cursor برای صفحه قبلی): در بعضی APIها برای برگشت به صفحه قبل استفاده می‌شود.

Total Count (تعداد کل رکوردهای مطابق فیلتر): برای نمایش تعداد کل نتایج استفاده می‌شود، اما در دیتای بزرگ ممکن است محاسبه آن سنگین باشد.

Filter Criteria (شرط‌های فیلتر مثل status، date، type): برای محدود کردن نتیجه API استفاده می‌شود.

Sorting (مرتب‌سازی خروجی بر اساس فیلد مشخص): برای پایداری pagination و جلوگیری از جابه‌جایی داده بین صفحات مهم است.

Stable Order (ترتیب ثابت و قابل تکرار داده‌ها): در pagination ضروری است تا رکوردها گم یا تکراری نشوند.

Duplicate Records (رکوردهای تکراری بین صفحات): یکی از failureهای رایج در pagination ضعیف است.

Missing Records (رکوردهای جاافتاده بین صفحات): وقتی pagination یا sorting ناپایدار باشد رخ می‌دهد.

Performance Risk (ریسک کندی یا فشار روی DB/API): در offsetهای بزرگ، فیلترهای سنگین یا total countهای پرهزینه دیده می‌شود.

400 Bad Request (خطای درخواست نامعتبر): برای پارامترهای نامعتبر مثل limit منفی، offset منفی یا date format غلط استفاده می‌شود.

Contract Validation (بررسی رفتار API طبق Swagger/OpenAPI یا مستندات): برای اطمینان از نام پارامترها، نوع داده، مقدارهای مجاز و خطاهای مورد انتظار استفاده می‌شود.

توضیح کوتاه پست

مرور فشرده‌ی Pagination و Filtering در API با تمرکز بر limit/offset، cursor-based pagination، ترکیب با sorting و ریسک‌هایی مثل رکورد تکراری، رکورد جاافتاده و فشار روی دیتابیس.

تگ‌ها

#APITesting
#Pagination
#Filtering
#BackendTesting
#RESTAPI