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 داریم، شما هم می‌توانید نیازهای جدید خود یا اشکالات احتمالی موجود را از طریق فرم مندرج در پایین صفحه برای ما ارسال کنید تا انشاءالله اضافه شود.
  • ارسال نظرات و سوالات

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

لطفاً نظر خود را بنویسید:

*
نظرات مخاطبان : [ تعداد نظرات منتشره : 24 نظر ]
  • سجاد ،
    1394-02-01 - 20:42

    سلام
    وجود سیستم Rss خوبه ولی لطفا خروجی JSON رو هم به سیستم اضافه کنید.
  • محمد حسین اصغری بقالان ،
    1394-01-17 - 12:01

    با عرض سلام و تحیت
    سایت خوبه ولی از لحاظ api ضعیفه
    مثلا اینکه عکس ها رو در دسته بندی مختلف نمیده !!‌
    یا خیلی چیزای دیگه
    بنده برنامه نویس وب و اندروید هستم و نیتهای خوبی برای پیاده سازی چند نرم افزار دارم 
    در صورت تمایل با ایمیل اینجانب تماس حاصل نمایید . 
    والسلام عل من اتبع الهدی
  • علی اسدی ،
    1393-05-22 - 18:54

    دستتون درد نکنه خیلی عالیه ما که برای سایتمون استفاده کردیم ...
    باز هم ممنون
    التماس دعا
  • محسن ،
    1393-05-10 - 07:18

    خوب است امکانی قرار دهید که بشود آخرین جمله مهم رهبری را نمایش داد.
    با تشکر
  • مهدی عرفان ،
    1393-05-02 - 15:50

    با سلام و آرزوی قبولی طاعات و عبادات 
    در صورتی که امکان خروجی از نوع json وجود دارد برای ای پی آی طراحی کنید 
    این نوع خروجی برای برنامه نویسی اندروید بسیار کارآمد است .
    من الله توفیق 
    مهدی عرفان 
  • داوود باقری فارسی ،
    1393-04-09 - 23:55

    سلام.خیلی غالیه.من حتما از این امکانات استفاده میکنم
  • محسن ،
    1392-12-24 - 22:18

    سلام خسته نباشید
    حاجی این استفتائات رو هم در یابید ، اگر api اش درست بشه ان شاء الله میشه که تو حوزه موبایل و آندروید هم برای سایت آقا کارهای خوبی کرد...
    این دفعه دومه کامنت میدم
    یاعلی
  • عمارگراف ،
    1392-12-17 - 13:06

    سلام
    خداقوت
    یعنی خداییش آرزومه یه روزی همه جاهای این كشور مثل این سایت منظم و دقیق و فعال و كاربلد و به فكر مردم باشن.به خدا جدّی میگم.دیگه بعدش هیچ مشكلی نداریم.
    دمتون گرم
    آقا شما اینجا خیلی كارهای خوبی میكنید.به نظرتون بهتر نیست یه فرصت یا جایی فراهم كنید تا بقیه هم بتونن از تجربیات و علم شما استفاده كنن(البته اگه خودتون بخواین)
    بازم ممنون
    راستی یه مثال كاربردی از روش اجرا و نمایش این API بزنید خیلی خوب میشه.یعنی هم لینك و دستور باشه هم یه صفحه نمونه برای نمایش خروجی.
    یا علی
  • محمدهادی حسین پور ،
    1392-11-03 - 01:42

    سلام علیكم و رحمة الله
    از آنجایی كه كاربرد API در ساخت برنامه ها بسیار بالا است و كمبود یك برنامه آندروید كامل برای این وب سایت حس می شود، بهتر است كه راهنمایی به صورت PDF همراه با مثال های متعدد به این جهت قرار داده شوند.
    
    اللهم عجل لولیك الفرج و العافیة و النصر
  • محمدرضا ،
    1392-08-22 - 07:19

    با سلام و احترام
    بنده برنامه نویس اندروید هستم و قصد دارم نسخه اندروید این وب سایت را طراحی نمایم،در صورت تمایل لطفا با من تماس حاصل فرمایید
  • سيد مهدی ميرحسنی ،
    1392-07-30 - 19:47

    سلام عليكم
    احتراما خواهشمند است اقدام لازم را جهت عضويت در سايت  از طريق پست الكترونيكی مبذول فرماييد
          
    باتشكر
    
    
    
    
    
    
    
    
  • محمد جواد ،
    1392-07-09 - 11:40

    با عرض سلام و خسته نباشید
    ما سایت مسجدمان را با جوملا طراحی كرده ایم. و از embed codeهایی كه در قسمت های مختلف هستند استفاده نموده ایم. اگر می شود راهنمایی بیشتری برای استفاده از API به ما بفرمائید.
    ضمنا عكس هایی كه فقط یكی از آنها موجود است مثل اینفوگراف ها و ... در سایت embed نمی شوند. 
    با تشكر و سپاس فراوان
    سایه امام خامنه ای بر سرمان مستدام باد
  • توحید عزیزی ،
    1392-04-08 - 09:30

    با عرض سلام.
    (1) آیا سرویس ای.پی.آی با خروجی
    JSON
    نیز موجود است؟
    (2) آیا سرویس ای.پی.آی برای زبان های دیگر، به ویژه انگلیسی نیز موجود است؟
  • مجتبی ،
    1392-03-18 - 15:35

    سایت بسیار خوب و منظمی ساخته اید. تبریك می گم، این سایت مایه سربلندی و افتخاره. و خوشبختانه سرویس دهی مناسب و چند جانبه ای داره. معلومه كه تحلیل كاربری می شه.
    به نوبه خودم از شما تشكر میكنم و به كل مجموعه خسته نباشید عرض می كنم. علی یارتون
  • حمید ملزوماتی خیابانی ،
    1392-03-16 - 20:19

    سلام 
    بسیار عالی است 
    مشخص است كه یك تیم كاملا خبره و كارآمد روی این سایت زحمت كشیده است .
    خسته نباشید آروزی طول عمر با عزت و بركت برای همه متخصصین متعهد و ولایت مدار.
    
  • حسین ،
    1392-02-26 - 05:57

    سلام علیكم.
    
    نیاز ما اكنون خروجی آیات مورد استفاده حضرت آقا با توجه به سوره و شماره آیه در خروجی است.
    
    در صورت امكان خواهشمند است خروجی  ای تحت عنوان شماره سوره و آیه به همراه تیتر و متن در اختیار قرار گیرد.
    
    پیشاپیش از بذل توجهتان تشكر می گردد.
  • مجید ،
    1391-12-27 - 00:52

    سلام
    ای پی آی برای خبرها به روز بروز نیست.
    ''به طور مثال در لینك اخبار سایت خبر امروز آمده است  ولی در ای پی آی خیر
    با تشكر
  • مهندس حشمت ،
    1391-12-25 - 18:18

    با سلام و تبریك پیشاپیش عید نوروز
    میخواستم از مسولین و دست اندكاران بیت آقا خواهش كنم بیانات آقا كه در تمام خطبه های عقد جمع آوری شده و روی سایت گذاشتید را بصورت كتاب دربیاورید تا بتوان هدیه كرد.
    تشكر
  • 1391-12-23 - 10:58

    سلام و خدا قوووووووووووووووت
    واقعا دمتون جوش!!!!!
  • ینده خدا ،
    1391-12-22 - 22:18

    واقعا یه سر و گردن بالاتر از سایت های ایرانی فعالیت میكنید.
    
    با تشكر
  • سیدیونس كاظمی ،
    1391-12-22 - 11:05

    درود بر شما
    بسیار خوشحال شدم :)
  • 1391-12-22 - 00:10

    ممنون ، استفاده كردیم . خدا آقارو برا ما نگه داره . 
  • علی ،
    1391-12-21 - 10:01

    لینكی كه به صفحه Api دادید اشتباه نیست؟
  • امیرحسین م ،
    1391-12-17 - 23:00

    سلام و تشكر بابت زحماتی كه می كشید
    اگر ممكنه فرمت JSON  را به خروجی ها تون اضافه كنید
    از لحاظ سرعت و راحتی در پردازش خیلی راحت تره.
    
    موفق باشید
پايگاه اطلاع‌رسانی دفتر حفظ و نشر آثار حضرت آيت‌الله‌العظمی سيدعلی خامنه‌ای (مد‌ظله‌العالی) - مؤسسه پژوهشی فرهنگی انقلاب اسلامی