مفاهیم اولیـه

معرفی 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>

در صورتی کـه مایل هستید بافرمت XML خروجی را دریـافت کنید کافیست پسوند آدرس مورد نظر را از JSON بـه XML تغییر دهید.

این متد تاریخ و زمان سرور کاوه نگار و همچنین زمان معادل آن بـه فرمت UnixTime را بـه شما نشان مـیدهد
کلیـه فیلد های مربوط بـه تاریخ درون وب سرویس کاوه نگار بـه فرمت UnixTime مـی باشد . شناسه چند رقمی است دلیل استفاده از این فرمت جلوگیری از بروز خطا درون هنگام پردازش آنـهاست. شناسه چند رقمی است به منظور آشنائی با فرمت UnixTime مـی توانید بـه اینجا مراجعه کنید و همچنین نمونـه کد تبدیل آن را به منظور زبان های برنامـه نویسی مختلف از اینجا دریـافت کنید.

فرمت فراخوانی متد ها

http(s)://api.kavenegar.com/v1/Your-Api-Key/Scope/MethodName.OutputFormat

در صورتی کـه 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 سرور قادر بـه پاسخگوئی نیست بعدا تلاش کنید.



[خدمات پیـام کوتاه کاوه نگار | مستندات ارسال پیـامک شناسه چند رقمی است]

نویسنده و منبع |