مستندات API باندی

با API باندی می‌توانید محتوای وبلاگ خود را در هر پلتفرمی نمایش دهید. از وب‌سایت React گرفته تا اپلیکیشن موبایل.

نصب سریع

npm install @bondi/client @bondi/react

احراز هویت

برای استفاده از API، به یک API Key نیاز دارید. کلید API را از پنل مدیریت تنانت خود دریافت کنید.

توجه: API Key را در کد سمت کلاینت قرار ندهید. از Server-Side rendering یا API Routes استفاده کنید.

curl -X GET "https://api.bondi.ir/v1/posts" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json"

Endpointها

Base URL: https://api.bondi.ir

GET/v1/posts

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

پارامترها:

نامنوعتوضیح
pagenumberشماره صفحه (پیش‌فرض: 1)
limitnumberتعداد در صفحه (حداکثر: 50)
statusstringوضعیت پست: PUBLISHED, DRAFT
categorystringفیلتر بر اساس slug دسته‌بندی
GET/v1/posts/:slug

دریافت یک پست با slug

GET/v1/categories

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

پارامترها:

نامنوعتوضیح
pagenumberشماره صفحه
limitnumberتعداد در صفحه
GET/v1/media

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

پارامترها:

نامنوعتوضیح
pagenumberشماره صفحه
limitnumberتعداد در صفحه (حداکثر: 100)
typestringنوع فایل: image, video, audio, document
GET/v1/search

جستجو در پست‌ها

پارامترها:

نامنوعتوضیح
q*stringعبارت جستجو (حداقل ۲ کاراکتر)
pagenumberشماره صفحه
limitnumberتعداد در صفحه

نمونه پاسخ

{
  "data": [
    {
      "id": "clx...",
      "title": "عنوان پست",
      "slug": "post-slug",
      "excerpt": "خلاصه پست...",
      "featuredImage": "https://...",
      "publishedAt": "2024-01-15T10:30:00Z",
      "author": {
        "id": "usr...",
        "name": "نام نویسنده",
        "avatar": "https://..."
      },
      "categories": [
        { "id": "cat...", "name": "تکنولوژی", "slug": "tech" }
      ],
      "tags": [
        { "id": "tag...", "name": "React", "slug": "react" }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5,
    "hasMore": true
  }
}

JavaScript SDK

SDK باندی استفاده از API را ساده‌تر می‌کند. TypeScript کامل پشتیبانی می‌شود.

import { BondiClient } from '@bondi/client';

const client = new BondiClient({
  apiKey: 'sk_live_your_api_key',
  baseUrl: 'https://api.bondi.ir'
});

// دریافت لیست پست‌ها
const { data: posts, pagination } = await client.getPosts({
  page: 1,
  limit: 10
});

// دریافت یک پست
const post = await client.getPost('my-post-slug');

// جستجو
const results = await client.search('کلمه کلیدی');

React Hooks

برای پروژه‌های React، از هوک‌های آماده استفاده کنید.

هوک‌های موجود:

  • usePosts() - دریافت لیست پست‌ها با pagination
  • usePost(slug) - دریافت یک پست
  • useCategories() - دریافت دسته‌بندی‌ها
  • useMedia() - دریافت فایل‌های رسانه
  • useSearch(query) - جستجو
  • useInfinitePosts() - Infinite scroll
import { BondiProvider, usePosts, usePost } from '@bondi/react';

// در App.tsx
function App() {
  return (
    <BondiProvider
      apiKey="sk_live_your_api_key"
      baseUrl="https://api.bondi.ir"
    >
      <BlogList />
    </BondiProvider>
  );
}

// در کامپوننت
function BlogList() {
  const { posts, loading, error, hasMore, loadMore } = usePosts();

  if (loading) return <div>در حال بارگذاری...</div>;
  if (error) return <div>خطا: {error.message}</div>;

  return (
    <div>
      {posts.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.excerpt}</p>
        </article>
      ))}
      {hasMore && (
        <button onClick={loadMore}>بارگذاری بیشتر</button>
      )}
    </div>
  );
}

مدیریت خطا

API در صورت بروز خطا، کدهای HTTP استاندارد برمی‌گرداند.

کدتوضیح
400پارامتر نامعتبر
401API Key نامعتبر یا ارائه نشده
403دسترسی غیرمجاز
404منبع یافت نشد
429تعداد درخواست بیش از حد مجاز
500خطای سرور

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

پلندرخواست در دقیقهدرخواست در روز
Free601,000
Startup30050,000
Business1,000نامحدود
Enterpriseسفارشینامحدود