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

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

در این سند

• در این سند
• احراز هویت
• ساختار API
• نقاط پایانی موجود
  • دریافت پست‌ها
  • دریافت جزئیات پست
  • دریافت دسته‌بندی‌ها
• مدیریت خطاها
• محدودیت‌های نرخ درخواست
• نتیجه‌گیری

احراز هویت

important

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

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

Api-Key: {{api-key}}

ساختار API

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

نقاط پایانی موجود

دریافت پست‌ها

درخواست

GET /api/v3/client/posts

GET /api/v3/client/posts?page=1&per_page=10&sort=published_at:desc
Api-Key: {{api-key}}

پاسخ

پاسخ

{
  "data": [
    {
      "id": 1,
      "title": "عنوان پست اول",
      "slug": "first-post-slug",
      "excerpt": "خلاصه‌ای از پست اول...",
      "content": "محتوای کامل پست اول...",
      "published_at": "2025-01-15T10:30:00Z",
      "author": {
        "id": 5,
        "name": "نویسنده نمونه"
      },
      "categories": [
        {
          "id": 3,
          "name": "اخبار"
        }
      ],
      "tags": [
        {
          "id": 7,
          "name": "فناوری"
        }
      ],
      "featured_image": {
        "url": "https://example.com/images/post1.jpg",
        "alt": "تصویر شاخص پست اول"
      }
    },
    // پست‌های بیشتر...
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 45,
    "total_pages": 5
  }
}

دریافت جزئیات پست

درخواست

GET /api/v3/client/posts/{id}

GET /api/v3/client/posts/1
Api-Key: {{api-key}}

پاسخ

پاسخ

{
  "data": {
    "id": 1,
    "title": "عنوان پست اول",
    "slug": "first-post-slug",
    "excerpt": "خلاصه‌ای از پست اول...",
    "content": "محتوای کامل پست اول...",
    "published_at": "2025-01-15T10:30:00Z",
    "author": {
      "id": 5,
      "name": "نویسنده نمونه"
    },
    "categories": [
      {
        "id": 3,
        "name": "اخبار"
      }
    ],
    "tags": [
      {
        "id": 7,
        "name": "فناوری"
      }
    ],
    "featured_image": {
      "url": "https://example.com/images/post1.jpg",
      "alt": "تصویر شاخص پست اول"
    },
    "related_posts": [
      {
        "id": 2,
        "title": "پست مرتبط",
        "slug": "related-post"
      }
    ]
  }
}

دریافت دسته‌بندی‌ها

درخواست

GET /api/v3/client/categories

GET /api/v3/client/categories
Api-Key: {{api-key}}

پاسخ

پاسخ

{
  "data": [
    {
      "id": 1,
      "name": "اخبار",
      "slug": "news",
      "post_count": 15
    },
    {
      "id": 2,
      "name": "فناوری",
      "slug": "technology",
      "post_count": 8
    },
    {
      "id": 3,
      "name": "آموزش",
      "slug": "tutorials",
      "post_count": 22
    }
  ]
}

مدیریت خطاها

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

کد وضعیت	پیام خطا	توضیحات
401	Unauthorized	کلید API نامعتبر یا گم شده است
404	Resource not found	منبع درخواستی یافت نشد
429	Too many requests	محدودیت نرخ درخواست رعایت نشده است

محدودیت‌های نرخ درخواست

API کلاینت دارای محدودیت‌های نرخ درخواست است تا از سوءاستفاده جلوگیری شود:

• 60 درخواست در دقیقه برای هر کلید API
• 1000 درخواست در روز برای هر کلید API

هدرهای زیر در پاسخ‌ها برای کمک به مدیریت محدودیت نرخ درخواست گنجانده شده‌اند:

هدرهای محدودیت نرخ درخواست

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1609459200

نتیجه‌گیری

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