نمای کلی API مدیریت

این سند نمای کلی از نقاط پایانی API مخصوص مدیریت را در نسخه 3 ارائه می‌دهد. این نقاط پایانی برای برنامه‌های مدیریتی طراحی شده‌اند و نیاز به مجوزهای بالاتری دارند.

در این سند

در این سند
احراز هویت
ساختار API
ماژول‌های موجود
مجوزها
ویژگی‌های خاص مدیریت
مثال استفاده

احراز هویت

الزامات امنیتی

نقاط پایانی API مدیریت نیاز به احراز هویت با استفاده از توکن Bearer دارند. توکن باید در هدرهای درخواست گنجانده شود:

هدر احراز هویت
Authorization: Bearer {your-access-token}

کاربر مرتبط با توکن باید مجوزهای لازم برای عملیات درخواستی را داشته باشد. اگر کاربر مجوزهای لازم را نداشته باشد، یک پاسخ 403 Forbidden برگردانده خواهد شد.

ساختار API

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

ماژول‌های موجود

ماژول CMS
ماژول کاربر
ماژول سیستم

ماژول CMS

ماژول CMS دسترسی مدیریتی به ویژگی‌های مدیریت محتوا را فراهم می‌کند:

ویژگی‌ها شامل:

پست‌ها: ایجاد، به‌روزرسانی، حذف و مدیریت پست‌ها
دسته‌بندی‌ها: مدیریت دسته‌بندی‌های محتوا و طبقه‌بندی‌ها
رسانه: مدیریت فایل‌های رسانه‌ای و گالری‌ها

مجوزها

نیاز به مجوز

نقاط پایانی API مدیریت به مجوزهای خاصی بر اساس نقش کاربر نیاز دارند. اگر کاربر مجوزهای لازم را نداشته باشد، یک پاسخ 403 Forbidden با جزئیاتی درباره مجوز گم شده برگردانده خواهد شد:

پاسخ رد مجوز
{
  "status": false,
  "error": {
    "code": "permission_denied",
    "message": "شما مجوز انجام این عملیات را ندارید",
    "details": {
      "required_permission": "cms.posts.create"
    }
  }
}

ویژگی‌های خاص مدیریت

API مدیریت چندین ویژگی را ارائه می‌دهد که در API کلاینت موجود نیستند:

عملیات دسته‌ای
مدیریت پیش‌نویس
تاریخچه نسخه‌ها
گزارش‌های ممیزی

عملیات دسته‌ای

بسیاری از نقاط پایانی API مدیریت از عملیات دسته‌ای برای مدیریت کارآمد پشتیبانی می‌کنند:

مثال حذف دسته‌ای
POST /api/admin/v3/cms/post/bulk/delete
Authorization: Bearer {your-access-token}
Content-Type: application/json

{
  "ids": [1, 2, 3, 4, 5]
}

مدیریت پیش‌نویس

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

مثال ایجاد پیش‌نویس
POST /api/admin/v3/cms/post
Authorization: Bearer {your-access-token}
Content-Type: application/json

{
  "title": "عنوان پست جدید",
  "content": {
    "short": "محتوای کوتاه",
    "full": "محتوای کامل"
  },
  "status": "draft"
}

تاریخچه نسخه‌ها

API مدیریت دسترسی به تاریخچه نسخه‌ها برای منابع پشتیبانی شده را فراهم می‌کند:

مثال دریافت نسخه‌ها
GET /api/admin/v3/cms/post/123/versions
Authorization: Bearer {your-access-token}

گزارش‌های ممیزی

API مدیریت گزارش‌های ممیزی دقیقی برای پیگیری تغییرات ارائه می‌دهد:

مثال گزارش ممیزی
GET /api/admin/v3/system/audit-log?resource_type=cms_post&resource_id=123
Authorization: Bearer {your-access-token}

مثال استفاده

درخواست پایه
ایجاد منابع
به‌روزرسانی منابع
حذف منابع

درخواست پایه

درخواست GET پایه
GET /api/admin/v3/cms/post
Authorization: Bearer {your-access-token}

ایجاد یک پست جدید

مثال درخواست POST
POST /api/admin/v3/cms/post
Authorization: Bearer {your-access-token}
Content-Type: application/json

{
  "title": "عنوان پست جدید",
  "content": {
    "short": "محتوای کوتاه",
    "full": "محتوای کامل"
  },
  "status": "draft"
}

به‌روزرسانی یک پست

مثال درخواست PUT
PUT /api/admin/v3/cms/post/1
Authorization: Bearer {your-access-token}
Content-Type: application/json

{
  "title": "عنوان پست به‌روزرسانی شده",
  "status": "published"
}

حذف یک پست

مثال درخواست DELETE
DELETE /api/admin/v3/cms/post/1
Authorization: Bearer {your-access-token}

در این سند​

احراز هویت​

ساختار API​

ماژول‌های موجود​

ماژول CMS​

ماژول کاربر​

ماژول سیستم​

مجوزها​

ویژگی‌های خاص مدیریت​

عملیات دسته‌ای​

مدیریت پیش‌نویس​

تاریخچه نسخه‌ها​

گزارش‌های ممیزی​

مثال استفاده​

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

ایجاد یک پست جدید​

به‌روزرسانی یک پست​

حذف یک پست​