مرجع API

قرارداد پاسخ

APIهای برنامه از یک envelope یکپارچه استفاده می‌کنند. پاسخ موفق شامل status و data است و پاسخ ناموفق message قابل نمایش یا ثبت در log دارد.

{
  "status": "success",
  "data": {
    "id": "resource_id"
  }
}

{
  "status": "error",
  "message": "A human-readable error"
}

GET /api/health

برای بررسی availability برنامه و پایگاه داده استفاده می‌شود. وضعیت 200 نشان‌دهنده سلامت و 503 نشان‌دهنده اختلال در یکی از وابستگی‌هاست.

{
  "status": "healthy",
  "timestamp": "2026-09-11T08:30:00.000Z",
  "checks": {
    "database": { "status": "up", "latencyMs": 12 }
  }
}

احراز هویت و دسترسی

مسیرهای وب محافظت‌شده از session و نقش‌های NextAuth استفاده می‌کنند. در نسخه فعلی API key عمومی منتشر نشده است؛ بنابراین کلید فرضی یا credential ساختگی در کلاینت قرار ندهید.

• ADMIN برای عملیات مدیریتی و CMS
• CLIENT و MEMBER برای قابلیت‌های حساب و پروژه
• STUDENT برای دسترسی‌های مرتبط با آکادمی

مدیریت خطا و محدودیت نرخ

کلاینت باید status HTTP را در کنار بدنه پاسخ بررسی کند. برای خطاهای موقت retry با backoff و برای خطاهای اعتبارسنجی اصلاح ورودی انجام دهید.

• ۴۰۰: ورودی نامعتبر یا ناقص
• ۴۰۱/۴۰۳: session یا نقش دسترسی کافی نیست
• ۴۲۹: تعداد درخواست بیش از محدودیت endpoint
• ۵۰۰/۵۰۳: خطای سرویس یا وابستگی؛ از retry نامحدود خودداری کنید