معرفی REST API

همان‌طور که شاید تا به حال شنیده باشید 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 می‌توانید به اینجا مراجعه کنید.

ساختار URL


http(s)://developers.parsijoo.ir/web-service/v1/sample/

کپی در حافظه

خطاهای مربوط به حساب کاربری:

429تعداد درخواست‌ها بیش از حد مجاز است.

403حساب کاربری معتبر نیست. این خطا در صورتی که کد شناسایی api-key اشتباه ارسال شود رخ می‌دهد.

پارامترهای خروجی:

کد وضعیت پاسخ

کد حاصل از اجرای متد که نشان‌دهنده اجرای موفق یا ناموفق آن است. در صورتی که مقدار آن ۲۰۰ باشد به معنای اجرای درست متد است و در غیر اینصورت باید به جدول ۱ماره ۱ کدهای برگشتی مراجعه کنید.

Integer

status
پیغام

String

message

خطا

مسلما بعد از اجرای هر متد نیاز است نتیجه حاصل از اجرای آن را دریافت و پردازش کنید. وب‌سرویس سیستم سفارشی پارسی‌جو برای سهولت این موضوع از فرمت خروجی رایج JSON استفاده کرده است: نتیجه حاصل از فراخوانی متد، توسط جدول کدهای برگشتی در Http Status Code برگشت داده می‌شود. برای مثال در صورتی که خطایی در هنگام اجرای درخواست اتفاق بیفتد مقدار 500 در Status Code قرار می‌گیرد. علاوه بر آن ساختار خروجی هم این خطا را نشان ‌می‌دهد. به خروجی زیر توجه کنید.


{
    "reqStatus": {
        "statusCode": 500,
        "message": "در انجام عملیات خطایی رخ داده است، لطفا دوباره تلاش کنید!"
    },
    "result": null
}

کپی در حافظه

خطاهای مربوط به پاسخ درخواست:

400پارامترها ناقص هستند.

404متدی با این نام پیدا نشده است.

405متد فراخوانی Get یا Post اشتباه است.

500خطا در انجام عملیات، بعدا تلاش کنید.

معرفی REST API

شروع

نتیجه

توضیحات

ساختار URL

خطاهای مربوط به حساب کاربری:

پارامترهای خروجی:

خطا

خطاهای مربوط به پاسخ درخواست:

سرویس‌های پارسی‌جو

ارزش افزوده

خدمات