وب سرویس RESTful با متدهای REST و به صورت امن HTTPS، طراحی شده و به راحتی در همهی زبانهای برنامهنويسی قابل استفاده می باشد. به دلیل سربار کم این سرويس، پهنای باند مصرفی در آن بسیار اندک خواهد بود.
سرویس مربوطه از تعدادی متد تشکیل شده است که هر یک از متدها برای کاربردی خاص
(ارسال پیامک، دریافت وضعیت پیامک های ارسال شده، دریافت پیامک، میزان اعتبار باقیمانده و ...) طراحی شده است.
برای استفاده از این سرویس کافیست که یکی از متدهای مربوط به سرویس را انتخاب
نموده و پارامترهای مخصوص به آن متد را تنظیم نموده، سپس پارامترهای مربوطه را از طریق متد POST و یا GET و در قالب Json به آدرس متد مربوطه ارسال نمایید.
متدهای سرویس :
متدهای پیاده سازی شده توسط سرویس به شرح ذیل می باشند :
حداکثر تعداد شماره های فرستنده، شماره های گیرنده و متن پیام ها در هر درخواست یکصد (۱۰۰) عدد می باشد. ارسال بيش از این تعداد با کد خطا مواجه خواهد شد.
در پاسخ تمامی متدها در صورتی که کد وضعیت پاسخ HTTP برابر با ۲۰۰ باشد عملیات با موفقیت انجام شده است، و هر کد وضعیت پاسخ Http دیگری نشانگر نوع خطای رخ داده در فراخوانی متد مربوطه می باشد.
کلیه فراخوانی های مربوط به متدهای وب سرویس RESTful شامل: تاریخ فراخوانی، آدرس IP، کد وضعیت پاسخ Http،
درخواست ارسالی، پاسخ ارسال شده توسط سرور و مشخصات سیستم ارسال کننده درخواست، از طریق منوی امکانات پیشرفته، خدمات وب، زیر منوی وب
سرویس RESTful، گزینه ی لیست فراخوانی متدهای وب سرویس قابل مشاهده می باشد.
آغاز کار با سرويس :
گام اول : ايجاد حساب کاربری در سامانه :
https://sms.smsafzar.ir
جهت دسترسی به وب سرویس می توانید یکی از دو روش احراز هویت زیر را انتخاب نمایید :
روش مبتنی بر توکن JWT :
به صورت پیش فرض، جهت دریافت توکن از کلمه عبور حساب کاربری استفاده میشود.
در صورت تمایل می توانید کلمه عبور مجزا جهت دریافت توکن تعریف نمایید، برای این منظور پس از ورود به حساب کاربری
خود از منوی امکانات پیشرفته، خدمات وب، زیر منوی وب سرویس RESTful، گزینه ی تنظیمات احراز هویت با توکن JWT را انتخاب نمایید و در
سر برگ تغییر کلمه عبور جهت دریافت توکن JWT، نسبت به تغییر کلمه عبور اقدام نمایید.
با استفاده از متد auth/token و ارائه نام کاربری، کلمه عبور (پیش فرض یا جدید) و نام دامنه، توکن صادر شده و در
سایر درخواست ها می بایست توکن دریافتی در هدر Authorization ارسال گردد.
تنظیمات امنیتی :
تعیین آدرس های IP معتبر : در صورت تمایل می توانید از منوی امکانات پیشرفته، خدمات وب، زیر منوی وب سرویس RESTful، گزینه ی تنظیمات احراز هویت با توکن JWT، سربرگ مدیریت آدرس های IP معتبر توکن JWT، نسبت به تعریف آدرس های IP معتبر جهت فراخوانی وب سرویس اقدام نمایید. در صورت تعیین آدرس های IP معتبر، درخواست هایی با مبدا غير از آدرس های IP تعریف شده با کد خطای 403 مواجه خواهند شد و سرویس از پاسخ گویی به این درخواست ها خودداری می نماید.
تعیین تاریخ انقضا توکن : به صورت پیش فرض تاریخ انقضا توکن دریافتی 7 روز می باشد در صورت تمایل می توانید از منوی امکانات پیشرفته، خدمات وب، زیر منوی وب سرویس RESTful، گزینه ی تنظیمات احراز هویت با توکن JWT، سربرگ تنظیمات توکن JWT، تاریخ انقضا دلخواه را برای توکن تعیین نمایید.
روش مبتنی بر Api Key :
این روش ساده و سریع است و نیاز به فرآیند دریافت توکن ندارد.
در این روش می توانید از طریق منوی امکانات پیشرفته، خدمات وب، مدیریت کلیدهای Api، گزینه ی تعریف کلید Api، کلید مورد نظر خود را
ایجاد نمایید.
کلید ایجاد شده می بایست در هدر کلیه ی درخواست ها با نام X-Api-Key ارسال گردد تا فرایند احراز هویت انجام گیرد.
تنظیمات امنیتی :
تعیین آدرس های IP معتبر : در صورت تمایل در زمان تعریف کلید Api می توانید نسبت به تعریف آدرس های IP معتبر جهت فراخوانی وب سرویس اقدام نمایید. در صورت تعیین آدرس های IP معتبر، درخواست هایی با مبدا غير از آدرس های IP تعریف شده با کد خطای 403 مواجه خواهند شد و سرویس از پاسخ گویی به این درخواست ها خودداری می نماید.
تعیین تاریخ انقضا کلید : شما می توانید کلید API را بدون تاریخ انقضا ایجاد نمایید یا برای کلید یک تاریخ انقضای دلخواه تعیین نمایید به این ترتیب پس از فرا رسیدن تاریخ انقضا، کلید به صورت خودکار منقضی شده و دیگر قابل استفاده نخواهد بود.
پس از تکمیل مراحل ثبت نام و انتخاب روش احراز هویت، اکنون می توانید متدهای وب سرویس RESTful را فراخوانی نمایید.
برای هر متد، پارامترهای مورد نیاز را تنظیم کرده و درخواست را از طریق متد HTTP مناسب (GET یا POST) ارسال نمایید.
توجه نمایید که هدرهای احراز هویت (Authorization برای توکن JWT یا X-Api-Key برای کلید API) باید در تمامی درخواست ها موجود باشند.
