مستندات API قرآن کریم

مقدمه

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

پایه آدرس (Base URL)

تمامی درخواست‌های API باید به آدرس زیر ارسال شوند:

https://sabyl.ir/api/

مشخصات کلی

فرمت پاسخ

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

پاسخ موفقیت‌آمیز:

{ "status": "success", "data": { // ... داده‌های درخواستی } }

پاسخ خطا:

{ "status": "error", "message": "توضیحات خطا" }

کدهای وضعیت HTTP

کد وضعیت	توضیحات
`200 OK`	درخواست با موفقیت انجام شد.
`400 Bad Request`	درخواست نامعتبر است (مثلاً پارامترهای الزامی ارسال نشده‌اند).
`404 Not Found`	منبع درخواستی (سوره، آیه یا مسیر API) یافت نشد.
`500 Internal Server Error`	خطایی در سمت سرور رخ داده است.

Endpoints

۱. سوره‌ها (Suras)

این بخش برای دریافت اطلاعات کلی سوره‌های قرآن استفاده می‌شود.

۱.۱. دریافت لیست تمام سوره‌ها

لیست تمام ۱۱۴ سوره قرآن را به ترتیب شماره برمی‌گرداند.

GET /suras

نمونه درخواست cURL:

curl -X GET https://sabyl.ir/api/suras

نمونه پاسخ موفقیت‌آمیز:

{ "status": "success", "data": [ { "id": 1, "name": "الفاتحه", "verse_count": 7 }, { "id": 2, "name": "البقرة", "verse_count": 286 } ] }

۱.۲. دریافت اطلاعات یک سوره خاص

اطلاعات یک سوره خاص را بر اساس شماره آن برمی‌گرداند.

GET /suras/{id}

پارامتر	نوع	توضیحات
`id`	integer	شماره سوره مورد نظر.

نمونه درخواست cURL:

curl -X GET https://sabyl.ir/api/suras/2

۲. آیات (Verses)

۲.۱. دریافت تمام آیات یک سوره

تمام آیات یک سوره خاص را به همراه متن عربی و ترجمه فارسی برمی‌گرداند.

GET /suras/{sura_id}/verses

نمونه درخواست cURL:

curl -X GET https://sabyl.ir/api/suras/1/verses

۳. جستجو (Search)

۳.۱. جستجو در ترجمه فارسی

در متن ترجمه فارسی تمام آیات قرآن جستجو کرده و نتایج را برمی‌گرداند.

GET /search/persian?q={query}

پارامتر	نوع	توضیحات
`q`	string	عبارت مورد جستجو.

نمونه درخواست cURL:

curl -X GET "https://sabyl.ir/api/search/persian?q=خدا"

۴. سرویس‌های ویژه (Utility)

۴.۱. دریافت آیه تصادفی

یک آیه به همراه ترجمه‌اش را به صورت تصادفی از کل قرآن برمی‌گرداند.

GET /random

نمونه درخواست cURL:

curl -X GET https://sabyl.ir/api/random

مثال کاربردی (JavaScript)

در اینجا یک مثال برای استفاده از API در جاوا اسکریپت (با استفاده از fetch) آورده شده است.

// تابعی برای دریافت لیست سوره‌ها
async function fetchSuras() {
  try {
    const response = await fetch('https://sabyl.ir/api/suras');
    const data = await response.json();
    console.log('لیست سوره‌ها:', data.data);
  } catch (error) {
    console.error('خطا در دریافت اطلاعات:', error);
  }
}

// تابعی برای جستجو
async function searchInPersian(query) {
  try {
    const response = await fetch(`https://sabyl.ir/api/search/persian?q=${encodeURIComponent(query)}`);
    const data = await response.json();
    console.log('نتایج جستجو:', data.data.results);
  } catch (error) {
    console.error('خطا در جستجو:', error);
  }
}

// استفاده از توابع
fetchSuras();
searchInPersian('رستگار');

مدیریت خطاها

در صورت بروز هرگونه خطا، API یک پاسخ JSON با کد وضعیت مناسب برمی‌گرداند. کلید message در پاسخ خطا، توضیحات مفصلی در مورد دلیل خطا ارائه می‌دهد.

مثال پاسخ خطا (404 Not Found):

{ "status": "error", "message": "سوره‌ای با این شماره یافت نشد." }