• ب
  • ب
  • ب
مرورگر شما توانایی چاپ متن با فونت درخواستی را ندارد!
1391/10/18

راهنمای استفاده از API

API چیست؟

APIاصطلاح API مخفف Application Programming Interface و به ‌معنی «رابط برنامه‌نویسی کاربردی» است. در حقیقت API همان پروتکل ارتباطی میان اجزاء نرم‌افزارها است که به آن‌ها امکان ارتباط برای دریافت و ارسال داده‌ها و اجرای توابع یکدیگر را می‌دهد.
به واسطه‌ی APIسایت Khamenei.ir، برنامه‌نویسان می‌توانند از محتواهای این سایت در نرم‌افزارها و وب‌سایت‌های مختلف استفاده کنند یا این‌که بانک اطلاعاتی مربوطه را روزآمد نگهدارند.
لذا اگر شما برنامه‌نویس یا صاحب سایت یا وبلاگ نیستید، شاید نیازی به خواندن ادامه‌‌ی این راهنما نداشته باشید.

چرا به API نیاز داریم؟

هرگاه بخواهید نرم‌افزاری مرتبط با بیانات رهبری را در محیط‌های گوناگون مثل وب (مثلاً سایت‌ها و وبلاگ‌ها) یا برنامه‌ی موبایل (مثلاً در سیستم‌ عامل اندروید یا ویندوز 8 یا سیمبین) یا برنامه‌ی دسک‌تاپ (مثلاً در لینوکس یا ویندوز) تولید کنید، قطعاً نیاز به یک بانک اطلاعات از بیانات رهبری با قابلیت روزآمدشدن هستید. با استفاده از این API می‌توانید چنین بانکی را ایجاد کنید و روزآمد نگهدارید.
همچنین با استفاده از خروجی RSS این API و یک نرم‌افزار RSS Reader می‌توانید در موبایل یا کامپیوتر خود نیز از محتواهای مختلف سایت با قابلیت سفارشی‌سازی کامل (به‌ وسیله‌ی ارسال Parameterهای لازم) بهره‌ ببرید.
اگر از سایتی استفاده می‌کنید که دارای امکان RSS Aggregator است، می‌توانید آخرین بیانات، اخبار، تصاویر و دیگر مطالب Khamenei.ir را در باکس ویژه‌ای در سایت خود درج کنید.

چگونه از API استفاده کنیم؟

URL دسترسی به API:

http://farsi.khamenei.ir/developer/api/news


با آدرس فوق و با استفاده از پارامترهایی که در جدول زیر آورده‌ایم، با متد GET می‌توانید حداکثر سفارشی‌سازی مورد نیاز را در دریافت محتوا اعمال نمایید:

پارامترهای دسترسی به محتوا (Parameters):

پارامترها الزامی مقادیر مجاز مقدار پیشفرض توضیحات
ver نیست 1 1 نسخه API مورد استفاده
news_type نیست لیست ضمیمه شماره 1* 2 کد نوع مطلب(بیانات، خبر یا...)
limit نیست از 1 تا 20 20 حداکثر تعداد رکورد خروجی
offset نیست از 1 تا تعداد ممکن 1 شماره ترتیب رکورد شروع
news_id نیست از 1 تا تعداد مطالب موجود --- کد مطلب
from_year نیست سال به شمسی 1368 از سال from_year به بعد
to_year نیست سال به شمسی 1393 تا قبل از سال to_year
response_format نیست rss rss فرمت خروجی
*سایر فرمت‌ها اضافه خواهدشد.
return_body نیست true, false false فیلد متن کامل
return_lead نیست true, false true فیلد چکیده
order نیست date_desc, date_asc, id_desc, id_asc date_desc ترتیب خروجی:
date_desc: جدید به قدیم
date_asc: قدیم به جدید
id_desc: کدمطلب و نزولی
id_asc:کدمطلب و صعودی
from_news_id نیست از 1 تا تعداد مطالب موجود --- نمایش از شناسه مورد نظر
to_news_id نیست از 1 تا تعداد مطالب موجود --- نمایش تا شناسه مورد نظر

چگونگی استفاده از پارامترهای فوق:

برای استفاده‌ی منعطف از API کافی است پارامترهای معرفی‌شده در بالا را به «آدرس دسترسی به API» با استفاده از متد GET ارسال نمایید. مثلاً اگر بخواهید پنج خبر آخر سایت Khamenei.ir را استخراج کنید، کافی است لینک زیر را اجرا نمایید تا سامانه با استفاده از response_format مشخص‌شده (یا پیش‌فرض) خروجی مورد نظر را در اختیار شما قرار دهد.

http://farsi.khamenei.ir/developer/api/news?news_type=1&limit=5

 


نوع مطلب(سرویس) مقدار پارامتر
خبر 1
بیانات 2
نقشه راه 3
پیام‌ها و نامه‌ها 4
حاشیه دیدار 5
عکس 6
فیلم 7
صوت 8
گزیده بیانات 9
پرونده 11
دیگران - یادداشت 12
دیگران - گفتگو 13
دیگران - خاطره 14
خاطرات 16
تلکس متنی 17
تلکس عکس 18
تلکس صوت 19
تلکس فیلم 20
دیگران - گزارش 22
مقاله 26
عکس ویژه 28
عکس پوستری 29
تلکس وبلاگی 30
ابلاغیه 32
بسته 33
شرح حدیث 34
کتاب 38
پیامک 39
صحیفه امام خمینی (ره) 40
شعر 43
عکس دیگران 44
برگزیده 45
تلمیحات و اشارات 46
دست نوشته 47
استفتائات 48
مرور سریع 49
روزنگار 50
چندرسانه‌ای 51
پیشخوان 52
داده تصویر 53
بیانات سیدحسن نصرالله 54
جدول ضمیمه 1



پاسخ به سؤالات پرکاربرد:
  • آیا استفاده از این سرویس به ثبت‌نام نیاز دارد؟

    خیر؛ فعلاً استفاده از سرویس Khamenei.ir API به صورت آزاد و رایگان در اختیار عموم قرار داده شده است و برای به‌کارگیری بخشی از یا تمام امکانات آن، به API Key نیازی نیست.
  • آیا در تعداد فراخوانی این API محدودیتی وجود دارد؟

    چنان‌چه تعداد Request ها از حد مجاز تعیین‌شده در دیواره‌ی آتش بیشتر شود و در نتیجه از سوی IP شما، تعداد غیر مجازی پکت با وضعیت SYN_SENT به سرور ارسال گردد، ممکن است برای دقایقی دسترسی با آن IP مسدود شود.
  • آیا پارامترها نسبت به کوچکی و بزرگی حروف حساس‌اند؟

    تمامی پارامترها و همچنین آدرس‌ها نسبت به کوچکی یا بزرگی حروف حساس‌ هستند و برای کاهش خطاهای کاربری، ما تمامی حروف را به‌صورت کوچک در نظر گرفته‌ایم.
  • من به لیست تمام بیانات نیازدارم اما خروجی این API حداکثر 20 مورد است، چگونه تمام مطالب را دریافت کنم؟

    شما می توانید با فراخوانی مکرر این API صفحات مختلف را دریافت کنید.
    مثلاً برای دریافت تمامی بیانات به ترتیب تاریخ، ابتدا لینک زیر را وارد نمائید:
    http://farsi.khamenei.ir/developer/api/news?news_type=2&order=date_asc&offset=0
    سپس تا رسیدن به زمانی که لینک زیر دیگر خروجی نداشته باشد، این را n بار اجراء کنید:
    http://farsi.khamenei.ir/developer/api/news?news_type=2&order=date_asc&offset=[20*n]
  • برای استفاده از API زبان برنامه نویسی خاصی لازم است؟

    خیر؛ به طور کلی هر زبانی که قابلیت استفاده از خروجی‌ای را داشته باشد که به واسطه‌ی response_format مشخص می‌شود، قابل استفاده است.
  • آیا استفاده از تمام پارامترها الزامی است؟

    خیر؛ استفاده از پارامترهای معرفی‌شده الزامی نیست و در صورتی که «URL دسترسی به API» را به‌تنهایی وارد کنید، خروجی با در نظر گرفتن مقادیر پیش‌فرض ارائه می‌شود.
    بدون هیچ پارامتری، 20 مطلب آخر از سرویس بیانات ارائه می‌شود.
  • در صورت ورود پارامترها و یا مقادیر غیرمجاز چه اتفاقی می افتد؟

    سامانه بر اساس پارامترهای پیش‌فرض نتیجه را برای شما ارائه خواهد کرد.
  • آیا سرویس API و انواع خروجی‌های آن ‌روزآمد خواهد شد؟

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

    در صورتی که سؤال یا نظری دارید، از طریق فرم زیر با ما درمیان بگذارید.
    خواهشمندیم قبل از ارسال، از عدم وجود سؤال خود در لیست سؤالات پرکاربرد مطمئن شوید.