صفحه‌بندی، فیلتر، خطاها و محدودیت نرخ

هر نقطهٔ پایانی فهرستی page و page_size می‌گیرد و همان پاکت را برمی‌گرداند. ‏total شمار همهٔ رکوردهای منطبق با فیلترهاست، نه اندازهٔ این صفحه - پس شمار صفحه‌ها Math.ceil(total / page_size) است.

curl -sS "https://your-host/api/v1/crm/contacts?page=2&page_size=100" \
  -H "Authorization: Bearer $CLIENTO_TOKEN"

{
  "items": [ { "id": 4182, "display_name": "Sara Ahmadi", "…": "…" } ],
  "page": 2,
  "page_size": 100,
  "total": 3417
}

‏q جست‌وجوی متن آزاد روی فیلدهایی است که یک آدم جست‌وجو می‌کند - نام، ایمیل، شرکت. بقیه پارامترهای پرس‌وجوی صریح‌اند و هر مجموعه، مجموعهٔ خودش را در سند OpenAPI مستند می‌کند.

# Free-text
curl -sS "https://your-host/api/v1/crm/contacts?q=ahmadi" \
  -H "Authorization: Bearer $CLIENTO_TOKEN"

# Typed filters (tasks)
curl -sS "https://your-host/api/v1/crm/tasks?status=open&priority=high&overdue=true" \
  -H "Authorization: Bearer $CLIENTO_TOKEN"

پارامتر پرس‌وجوی ناشناخته نادیده گرفته می‌شود نه رد - پس یک غلط تایپی به‌جای خطا، نتیجهٔ فیلترنشده برمی‌گرداند. اگر فیلتری انگار هیچ کاری نمی‌کند، نام پارامترها را با سند OpenAPI بسنجید.

هر رد شدنی، از بدنهٔ نادرست تا خطای داخلی، همان سه فیلد را برمی‌گرداند. هیچ‌چیز صفحهٔ خطای HTML برنمی‌گرداند، پس کلاینت هرگز مجبور نیست حدس بزند بدنه قابل تجزیه هست یا نه.

{
  "error": "validation_error",
  "message": "Invalid payload",
  "details": { "email": ["Not a valid email address."] }
}

• ‏`error` - کد ماشینی پایدار. شرط‌ها را بر همین بگذارید و بومی‌سازی را هم بر همین.
• ‏`message` - متن تشخیصی انگلیسی برای توسعه‌دهنده. به کاربر نهایی نشانش ندهید و رویش تطبیق ندهید؛ ممکن است بازنویسی شود.
• ‏`details` - ساختاری که با نوع خطا فرق می‌کند: خطای فیلدها برای اعتبارسنجی، required برای رد مجوز، reason برای قاعدهٔ کسب‌وکار، retry_after برای محدودیت نرخ. می‌تواند null باشد.

نقاط پایانی حساس - ورود، کدهای یک‌بارمصرف پرتال مشتری، ارسال فرم‌های عمومی، صفحهٔ عمومی فاکتور و بازگشت‌های پرداخت - به‌ازای هر فراخوانی‌کننده محدود می‌شوند. CRUD معمولیِ احراز‌هویت‌شده به‌طور پیش‌فرض محدود نیست، اما اپراتور فضای کاری می‌تواند محدودیت تنظیم کند؛ پس کلاینت خوش‌رفتار در هر حال ۴۲۹ را مدیریت می‌کند.

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "Too many requests",
  "details": { "retry_after": 42 }
}

• ‏Retry-After (به ثانیه) را رعایت کنید. این پاسخ خودِ سرور است - انتظار کوتاه‌تر فقط دوباره رد می‌شود.
• برای ۵xx با عقب‌نشینی نمایی و jitter عقب بکشید. فاصلهٔ تلاش ثابت، یک قطعی کوتاه را در لحظهٔ بازیابی به هجوم تبدیل می‌کند.
• ‏GET و DELETE را آزادانه دوباره بفرستید - خودتوان‌اند. برای POST بخش بعدی را ببینید.

هدر سراسری Idempotency-Key وجود ندارد. هرجا تکرار زیان‌بار باشد، خود نقطهٔ پایانی هویت خودتوانی‌اش را در بدنه می‌آورد و آن را اجباری می‌کند نه اختیاری - هویت در اختیار کلاینت است، چون فقط کلاینت می‌داند که این تلاش، تلاش دوباره است.

برای نقاط پایانی بدون فیلد خودتوانی، POSTای که تایم‌اوت شود سرانجام نامعلومی دارد. کورکورانه دوباره نفرستید: با یک GET روی چیزی که خودتان کنترل می‌کنید - مثلاً یک شناسهٔ بیرونی که روی رکورد ذخیره کرده‌اید - بازخوانی کنید و فقط اگر واقعاً نبود بسازید.