مفاهیم اولیه
معرفی REST API
همان طور که شاید تا به حال شنیده باشید API مخفف عبارت Application Programming Interface می باشد که به برنامه نویسان امکان رد و بدل کردن اطلاعات مابین پلتفرم های مختلف را از طریق ارسال یک درخواست HTTP(S) ساده و فراخوانی متد های مورد نظر می دهد
در واقع REST یکی روش ساده و انعطاف پذیری برای استفاده از API
است
و البته محبوب ترین و پر کاربرد ترین که می توان توسط این ساختار
از هر کلاینت و پلتفرمی درخواست ساده HTTP(S) را ارسال و پاسخ آن را دریافت نمود.
حال فرض کنید در خواست مورد نظر اطلاعات مربوط به ارسال یک پیامک باشد و جواب آن نتیجه و وضعیت پیامک ارسالی باشد
وب سرویس ارسال اس ام اس
کاوه نگار
شماره گیرنده ، متن پیامک و شماره فرستنده را از طریق پارامتر های ورودی در متد GET یا POST دریافت می کند و خروجی را در غالب فرمت های XML و JSON برگشت می دهد.
نکته : اگر با JSON آشنائی ندارید می توانید با مراجعه به سایت
json.org
هم از ساختار فرمت آن مطلع شوید و هم درایور مربوط به زبان برنامه نویسی مورد نظر خود را دریافت نمائید.
شروع
قبل از آن که در مورد ساختار خروجی متد ها توضیح دهیم این متد را باهم اجرا کنیم :
خروجی باید چیزی شبیه به این باشد :
{ "return": { "status":200, "message":"تایید شد" }, "entries": { "datetime":"02/06/2012 01:53:46 ب.ظ", "year":2012, "month":1, "day":26, "hour":13, "minute":53, "second":46, "unixtime":1338645226 } }
<response> <return> <status>200</status> <message>تایید شد</message> </return> <entries> <item> <datetime>02/06/2012 01:53:46 ب.ظ</datetime> <year>2012</year> <month>06</month> <day>02</day> <hour>13</hour> <minute>53</minute> <second>46</second> <unixtime>1338645226</unixtime> </item> </entries> </response>
این متد تاریخ و زمان سرور کاوه نگار و همچنین زمان معادل آن به فرمت UnixTime را به شما نشان میدهد
کلیه فیلد های مربوط به تاریخ در وب سرویس کاوه نگار به فرمت UnixTime می باشد .
دلیل استفاده از این فرمت جلوگیری از بروز خطا در هنگام پردازش آنهاست.
برای آشنائی با فرمت UnixTime می توانید به
اینجا
مراجعه کنید
و همچنین نمونه کد تبدیل آن را برای زبان های برنامه نویسی مختلف از
اینجا
دریافت کنید.
فرمت فراخوانی متد ها
در صورتی که API-KEY ندارید می توانید از این بخش ثبت نام کنید و 5،000 ریال هم اعتبار هدیه برای تست وب سرویس کاوه نگار دریافت کنید
شناسائی و اعتبار سنجی حساب کاربری Authorization در سرویس کاوه نگار توسط رشته API-KEY انجام میشود.
فراخوانی متد ها از طریق لایه SSL امکان پذیر است.
خطا های مربوط به حساب کاربری :
401 |
حساب کاربری غیر فعال است. |
403 |
حساب کاربری معتبر نمی باشد. این خطا در صورتی که کد شناسائی API-Key اشتباه ارسال شود رخ می دهد. |
ساختار خروجی
مسلما بعد از اجرای هر متد نیاز است نتیجه حاصل از اجرای آن را دریافت و پردازش کنید.
سرویس کاوه نگار برای سهولت این موضوع از دو فرمت خروجی رایج
JSON
و
XML
استفاده نموده است :
نتیجه حاصل از فراخوانی متد را توسط جدول کد های برگشتی در
Http Status Code
برگشت داده میشود
,
برای مثال در صورتی که متد مورد نظر وجود نداشته باشد مقدار
404
در
Status Code
قرار می گیرد .
علاوه بر آن ساختار خروجی هم این خطا را نشان میدهد برای مثال به خروجی زیر لطفا توجه نمائید.
{ "return": { "status":404, "message":"متد تعریف نشده است" }, "entries": { null } }
<response> <return> <status>404</status> <message>متد تعریف نشده است</message> </return> <entries> </entries> </response>
Status
کد حاصل از اجرای متد که نشان دهنده اجرای موفق یا ناموفق آن است ,در صورتی که مقدار آن 200 باشد به معنای اجرای درست متد است
و در غیر اینصورت باید به جدول
شماره 1 کد های برگشتی
مراجعه نمائید.
Message
توضیح مربوط به کد می باشد.
خطا های احتمالی در هنگام اجرای متد ها :
400 |
پارامترها ناقص هستند. |
402 |
عملیات ناموفق بود. |
404 |
متدی با این نام پیدا نشده است . |
405 |
متد فراخوانی Get یا Post اشتباه است . |
409 |
سرور قادر به پاسخگوئی نیست بعدا تلاش کنید. |