همانطور که شاید تا به حال شنیده باشید API مخفف عبارت Application Programming Interface است.API به برنامهنویسان امکان تبادل اطلاعات بین پلتفرمهای مختلف را از طریق ارسال یک درخواست HTTP(S) ساده و فراخوانی متدهای مورد نظر میدهد. REST یک روش ساده، انعطافپذیر و محبوب و پرکاربرد برای استفاده از API است. با استفاده از این ساختار میتوان از هر کلاینت و پلتفرمی درخواست ساده HTTP(S) را ارسال و پاسخ آن را دریافت کرد. در تمام وبسرویسهای سفارشی پارسیجو، اطلاعات ورودی از طریق پارامترها، در متد GET یا POST دریافت میشود و خروجی در قالب فرمت JSON برگشت داده میشود.
نکته: اگر با JSON آشنایی ندارید میتوانید با مراجعه به سایت json.org هم از ساختار فرمت آن مطلع شوید و هم درایور مربوط به
زبان برنامهنویسی مورد نظر خود را دریافت کنید.
قبل از اینکه در مورد ساختار خروجی متدها توضیح دهیم این متد را باهم اجرا کنیم:
http(s)://developers.parsijoo.ir/web-service/v1/sample/
کپی در حافظه
{
reqStatus: {
statusCode: 200,
message: null
},
result: {
datetime: "10 Sep 2017 06:14:00 GMT",
year: 117,
month: 8,
day: 0,
hour: 10,
minute: 44,
second: 0,
unixtime: 1505024040003
}
}
کپی در حافظه
این متد تاریخ و زمان سرور وبسرویسهای سفارشی پارسیجو و همچنین زمان معادل آن به فرمت UnixTime را به شما نشان میدهد. اکثر فیلدهای مربوط به تاریخ در وبسرویسهای سفارشی پارسیجو به فرمت UnixTime است.
نکته:دلیل استفاده از این فرمت جلوگیری از بروز خطا در هنگام پردازش آنهاست. برای آشنایی با فرمت UnixTime میتوانید به اینجا مراجعه کنید.
http(s)://developers.parsijoo.ir/web-service/v1/sample/
کپی در حافظه
429تعداد درخواستها بیش از حد مجاز است.
403حساب کاربری معتبر نیست. این خطا در صورتی که کد شناسایی api-key اشتباه ارسال شود رخ میدهد.
مسلما بعد از اجرای هر متد نیاز است نتیجه حاصل از اجرای آن را دریافت و پردازش کنید. وبسرویس سیستم سفارشی پارسیجو برای سهولت این موضوع از فرمت خروجی رایج JSON استفاده کرده است: نتیجه حاصل از فراخوانی متد، توسط جدول کدهای برگشتی در Http Status Code برگشت داده میشود. برای مثال در صورتی که خطایی در هنگام اجرای درخواست اتفاق بیفتد مقدار 500 در Status Code قرار میگیرد. علاوه بر آن ساختار خروجی هم این خطا را نشان میدهد. به خروجی زیر توجه کنید.
{
"reqStatus": {
"statusCode": 500,
"message": "در انجام عملیات خطایی رخ داده است، لطفا دوباره تلاش کنید!"
},
"result": null
}
کپی در حافظه
400پارامترها ناقص هستند.
404متدی با این نام پیدا نشده است.
405متد فراخوانی Get یا Post اشتباه است.
500خطا در انجام عملیات، بعدا تلاش کنید.