معرفی REST API

REST مخفف واژگان Representational State Transfer است که از سال ۲۰۰۵ در وب شناخته شد که در ظاهر کمی گیج‌کننده به نظر می‌رسد، اما با کمی توضیح، می‌توان این مفهوم در ظاهر پیچیده را رمزگشایی کرد!

اگر خیلی ساده بخواهیم به این قضیه نگاه کنیم، REST عبارت است از راه کارها و روش‌هایی که با استفاده از آن‌ها می‌توان به رد و بدل دیتا از طریق شبکه پرداخت. به عبارت دیگر، REST راهی ساده به منظور سازماندهی تعاملات مابین سیستم‌های مجزا از یکدیگر می‌باشد.

در مقابل REST، پروتکل SOAP که مخفف واژگان Simple Object Access Protocol است قرار دارد که از طریق آن می‌توان به رد و بدل دیتا از طریق شبکه در قالب وب سرویس های مختلفی با فرمت XML پرداخت.

API هم مخفف واژگان Application Programming Interface است که دربرگیرنده ی متدهایی برای ارتباط با سایر لایبرری ها یا اپلیکیشن ها است.

حال اگر این اصطلاحات در کنار یکدیگر قرار دهیم و چیزی تحت عنوان RESTful API بسازیم، منظورمان سازوکارهایی برای ارتباط با سایر سرویس ها با استفاده از معماری خاصی است. معماری REST دارای یکسری ویژگی‌ها است که شاخص ترین آن‌ها عبارتند از:

- ثبات و یکنواختی این معماری در جای جای API

- عدم برخورداری از سشن در سمت سرور

- به‌کارگیری از کدهای وضعیت اچ تی تی پی

- استفاده از یو آر ال ها برای مشخص ساختن مسیرهای مد نظر

- اِعمال کوئری ها در یو آر ال به جای هدر پروتکل اچ تی تی پی

با این تفاسیر، RESTful API ها به خدمت توسعه‌دهندگان وب آمده‌اند تا فرایند توسعه ی وب، ایجاد تجربه ی کاربری بهتر، سهولت در استفاده از ای پی آی ها و نقل و انتقال داده‌ها از طریق پروتکل اچ تی تی پی را امکان‌پذیر سازند.

علاوه بر این، توجه داشته باشیم که REST بیش از آنکه پروتکل باشد، یکسری راهنما، اصول و قواعدی است که با استفاده از آن‌ها می‌توانیم به برقراری ارتباط مابین منابع مختلف بپردازیم.

ارسال پیامک با استفاده از REST API

Request
    url= http://sms.3300.ir/api/wsSend.ashx

POST parameters
    username:USERNAME
    password:PASSWORD
    mobile:MOBILE
    message:MESSAGE_TEXT
    line:SMS_LINE_NUMBER
    line2:SMS_LINE_NUMBER2
    type:0
    template:0

Response sample
{
  "data": {
    "message_id": 3403,
    "line": 9830003300,
    "mobile": "989395213300"
  },
  "status": -1,
  "msg": "success"
}
                        
نکته: سرشماره‌هایی که با 3000شروع می‌شوند به صورت 983000 و سرشماره‌هایی که با 1000 شروع می‌شوند بدون 98 استفاده می‌شوند.
line2: اگر ارسال پیامک با line به خطای انصراف از دریافت خورد، پیامک با line2 ارسال می شود.
type: یکی از سه مقدار روبرو را می تواند داشته باشد: 0 = ارسال معمولی 1 = ارسال با چلچله 2 = ارسال با خط خدماتی نگین رایانه

سناریوی شماره یک : ارسال پیامک تکی

Request
    url= http://sms.3300.ir/api/wsSend.ashx

POST parameters
    username:USERNAME
    password:PASSWORD
    mobile:MOBILE
    message:MESSAGE_TEXT
    line:SMS_LINE_NUMBER
                        

سناریوی شماره دو : ارسال پیامک با خط خدماتی متعلق به نگین رایانه

Request
    url= http://sms.3300.ir/api/wsSend.ashx

POST parameters
    username:USERNAME
    password:PASSWORD
    mobile:MOBILE
    message:MESSAGE_TEXT
    type:2
                        

سناریوی شماره سه : ارسال پیامک با خط اینترنتی و پشتیبانی خط دوم

در صورتی که ارسال با خط اینترنتی به مشکل انصراف از دریافت برخورد کرد، ارسال با خط دوم انجام می شود

Request
    url= http://sms.3300.ir/api/wsSend.ashx

POST parameters
    username:USERNAME
    password:PASSWORD
    mobile:MOBILE
    message:MESSAGE_TEXT
    line:SMS_LINE_NUMBER
    line2:SMS_LINE_NUMBER2
                        

سناریوی شماره چهار : ارسال پیامک با خط اینترنتی و پشتیبانی چلچله

درصورتی که ارسال پیامک با خط اینترنتی به مشکل انصراف از دریافت برخورد کرد، ارسال از طریق چلچله انجام خواهد شد.

Request
    url= http://sms.3300.ir/api/wsSend.ashx

POST parameters
    username:USERNAME
    password:PASSWORD
    mobile:MOBILE
    message:MESSAGE_TEXT
    line:SMS_LINE_NUMBER
    type:1
                        

سناریوی شماره پنج : ارسال پیامک با خط اینترنتی و پشتیبانی خط خدماتی نگین رایانه

درصورتی که ارسال پیامک با خط اینترنتی به مشکل انصراف از دریافت برخورد کرد، ارسال از طریق خط خدماتی متعلق به نگین رایانه انجام خواهد شد.

Request
    url= http://sms.3300.ir/api/wsSend.ashx

POST parameters
    username:USERNAME
    password:PASSWORD
    mobile:MOBILE
    message:MESSAGE_TEXT
    line:SMS_LINE_NUMBER
    type:2
    template:0
                        
template: در صورتی که بیش از یک متن برای ارسال با خط خدماتی نگین رایانه وجود دارد شماره تمپلیت را ارسال کنید.

دریافت وضعیت پیامک با استفاده از REST API

درصورتی که ارسال پیامک با خط اینترنتی به مشکل انصراف از دریافت برخورد کرد، ارسال از طریق خط خدماتی متعلق به نگین رایانه انجام خواهد شد.

Request
    url= http://sms.3300.ir/api/wsStates.ashx

POST parameters
    username:USERNAME
    password:PASSWORD
    message_ids: "6062,6063,6064"
Response sample
{
"data": {
" msgIds": "6062,6063,6064",
  	"states":  "1,0,8"
  	},
"status": -1,
"msg": "success"
}

                        
message_ids: شناسه پیامکهایی که هنگام ارسال پیامک از سرور دریافت شده اند. این شناسه ها باید با کاما (,) از یکدیگر جدا شوند.
فیلد data در پاسخ بازگشتی از سرور در صورتی که فیلد status برابر 1- باشد دارای دو خصوصیت msgIds و states است.
فیلد msgIds شامل شناسه های پیام است که با کاما از هم جدا شده اند و فیلد states شامل وضعیت پیامها به صورت نظیر به نظیر با فیلد msgIds است و با کاما از هم جدا شده اند. وضعیت هر پیام می تواند یکی از کدهای زیر باشد:
1- : ارسال نشده به اپراتور 2: عدم دریافت توسط گوشی
0: نامشخص 8 : دریافت شده توسط اپراتور
1: دریافت توسط گوشی 16: عدم دریافت توسط اپراتور