مبانی API نسخه 3

این سند مروری بر مفاهیم و ویژگی‌های اساسی API نسخه 3 ارائه می‌دهد.

شروع به کار

اطلاع

نسخه V3 API بر اساس رویکردی متفاوت نسبت به V1 است، با مفاهیم جدیدی که برای مدیریت بهتر سرویس‌های وب طراحی شده‌اند. این سند این مفاهیم را معرفی می‌کند و راهنمایی‌هایی برای توسعه با آن‌ها ارائه می‌دهد.

در این نسخه، از دو مفهوم کلیدی استفاده می‌شود: ترنسفورمرها و ریپوزیتوری‌ها. این اجزا پایه و اساس معماری API نسخه 3 را تشکیل می‌دهند.

ترنسفورمرها
ریپوزیتوری‌ها

ساختار URL

API نسخه 3 از یک الگوی ساختار URL ثابت پیروی می‌کند:

https://api.example.com/api/{audience}/{version}/{module}/{resource}/{id?}

که در آن:

audience: مخاطب هدف را نشان می‌دهد (client یا admin)
version: نسخه API (v3)
module: نام ماژول (مثلاً cms، user، system)
resource: منبع خاص (مثلاً post، category، user)
id: شناسه منبع اختیاری برای عملیات‌های منبع خاص

مثال‌ها

کلاینت
مدیر

نقاط پایانی کلاینت
# لیست تمام پست‌ها
GET https://api.example.com/api/client/v3/cms/post

# دریافت یک پست خاص
GET https://api.example.com/api/client/v3/cms/post/123

# جستجوی پست‌ها
GET https://api.example.com/api/client/v3/cms/post?search=hello

نقاط پایانی مدیر
# لیست تمام کاربران
GET https://api.example.com/api/admin/v3/user/user

# ایجاد کاربر جدید
POST https://api.example.com/api/admin/v3/user/user

# به‌روزرسانی کاربر
PUT https://api.example.com/api/admin/v3/user/user/456

# حذف کاربر
DELETE https://api.example.com/api/admin/v3/user/user/456

احراز هویت

تمام درخواست‌های API نیاز به احراز هویت دارند. API از احراز هویت مبتنی بر توکن استفاده می‌کند.

دریافت توکن

برای دریافت توکن، باید به نقطه پایانی ورود درخواست ارسال کنید:

POST https://api.example.com/api/client/v3/auth/login

با بدنه درخواست:

{
  "email": "user@example.com",
  "password": "your_password"
}

پاسخ شامل توکن دسترسی خواهد بود:

{
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "expires_at": "2025-06-26T18:42:13+03:30"
  }
}

استفاده از توکن

توکن را در هدر Authorization با پیشوند Bearer اضافه کنید:

GET https://api.example.com/api/client/v3/cms/post
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

پاسخ‌های استاندارد

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

{
  "data": {
    // داده‌های اصلی پاسخ
  },
  "meta": {
    // اطلاعات اضافی مانند صفحه‌بندی
  }
}

مثال پاسخ

{
  "data": [
    {
      "id": 1,
      "title": "عنوان اول",
      "content": "محتوای پست اول"
    },
    {
      "id": 2,
      "title": "عنوان دوم",
      "content": "محتوای پست دوم"
    }
  ],
  "meta": {
    "pagination": {
      "total": 50,
      "count": 2,
      "per_page": 2,
      "current_page": 1,
      "total_pages": 25
    }
  }
}

پارامترهای درخواست

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

پارامتر	نوع	توضیحات	مثال
page	عدد	شماره صفحه برای صفحه‌بندی	`page=2`
limit	عدد	تعداد نتایج در هر صفحه	`limit=25`
search	رشته	جستجوی عمومی در تمام فیلدهای قابل جستجو	`search=hello`
searchJoin	رشته	نحوه ترکیب چندین عبارت جستجو (`and` یا `or`)	`searchJoin=and`
filter	آرایه	فیلتر بر اساس مقادیر فیلد خاص	`filter[]=status:published`
orderBy	رشته	فیلد برای مرتب‌سازی نتایج	`orderBy=created_at`
sortedBy	رشته	جهت مرتب‌سازی نتایج (`asc` یا `desc`)	`sortedBy=desc`
includes	رشته	موجودیت‌های مرتبط برای گنجاندن در پاسخ	`includes=author,category,tags`

مدیریت خطا

در صورت بروز خطا، API یک پاسخ خطای استاندارد با کد وضعیت HTTP مناسب برمی‌گرداند:

{
  "error": {
    "code": "validation_error",
    "message": "داده‌های ارائه شده نامعتبر هستند",
    "details": {
      "title": ["عنوان الزامی است"]
    }
  }
}

کدهای وضعیت HTTP رایج

کد	معنی	توضیحات
200	OK	درخواست موفقیت‌آمیز بود
201	Created	منبع با موفقیت ایجاد شد
400	Bad Request	درخواست نامعتبر است
401	Unauthorized	احراز هویت لازم است
403	Forbidden	کاربر احراز هویت شده مجاز به انجام این عمل نیست
404	Not Found	منبع درخواست شده یافت نشد
422	Unprocessable Entity	خطای اعتبارسنجی
500	Internal Server Error	خطای سرور

شروع به کار​

ساختار URL​

مثال‌ها​

احراز هویت​

دریافت توکن​

استفاده از توکن​

پاسخ‌های استاندارد​

مثال پاسخ​

پارامترهای درخواست​

مدیریت خطا​

کدهای وضعیت HTTP رایج​