مستندات API رهگنج

شروع سریع

1. از مدیر سامانه یک توکن API با scope مناسب دریافت کنید.
2. توکن را در هدر Authorization: Bearer … یا X-API-Key ارسال کنید.
3. ابتدا endpoint /health را بدون توکن آزمایش کنید تا از اتصال مطمئن شوید.

احراز هویت

توکن‌ها با پیشوند rgj_live_ صادر می‌شوند و فقط یک بار در لحظه ساخت نمایش داده می‌شوند. مقدار خام هرگز در دیتابیس نگه‌داری نمی‌شود (فقط hash).

curl -H "Authorization: Bearer rgj_live_..." \
  "https://rahganj.ir/api/public/v1/speeches?size=5"

محدودیت نرخ

هر کلید سقف دقیقه/روز مستقل دارد. پاسخ‌ها هدرهای X-RateLimit-Limit، X-RateLimit-Remaining و X-RateLimit-Reset را ارسال می‌کنند. در صورت عبور، پاسخ 429 با هدر Retry-After دریافت می‌کنید.

قالب پاسخ / خطا

// موفق
{ "data": {...}, "meta": { "request_id": "...", "page": 1, "size": 20, "total": 137 } }

// خطا
{ "error": { "code": "invalid_token", "message": "...", "request_id": "..." } }

کدهای خطا: missing_token، invalid_token، revoked_token، expired_token، insufficient_scope، rate_limited، invalid_query، not_found، internal_error.

مرجع Endpointها

بهترین روش‌ها برای مصرف

• توکن را فقط در سمت سرور نگه‌داری کنید (متغیر محیطی)، نه در مرورگر یا کد کلاینتی.
• پاسخ‌های عمومی هدر Cache-Control با s-maxage برمی‌گردانند؛ آن‌ها را کش کنید تا با هر درخواست بات یک کوئری تازه ایجاد نکنید.
• روی 429 از هدر Retry-After و backoff نمایی استفاده کنید. بیشتر از ۴ بار تلاش نکنید.
• برای «وظیفهٔ روز» از /tasks/random?featured=true استفاده کنید (سبک و بدون کش).
• برای متن آمادهٔ ارسال در پیام‌رسان‌ها از /today-in-history?include=paragraphs&limit=1 استفاده کنید.

// Node/TS client with retry + Retry-After
export async function rahganjFetch(path: string) {
  const url = `https://rahganj.ir/api/public/v1${path}`;
  for (let attempt = 0; attempt < 4; attempt++) {
    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.RAHGANJ_API_KEY!}` },
    });
    if (res.status === 429 || res.status >= 500) {
      const wait = Number(res.headers.get("retry-after") ?? 2 ** attempt);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    if (!res.ok) throw new Error(`Rahganj ${res.status}: ${await res.text()}`);
    return await res.json();
  }
  throw new Error("Rahganj: too many retries");
}

Playground