API و وب‌سرویس چه فرقی دارند؟ REST، SOAP و JSON به زبان ساده

تیم وب‌سرویس ۱۳ مهر ۱۴۰۵ برنامه‌نویسان

کسی که برای اولین بار مستندات یک وب‌سرویس را باز می‌کند، با رگباری از اصطلاحات روبه‌رو می‌شود: API، REST، JSON، کد ۲۰۲، Bearer… خبر خوب این است که پشت همهٔ این‌ها چند ایدهٔ ساده است. در این مقاله آن‌ها را با مثال ارسال پیامک باز می‌کنیم.

API چیست؟

API (رابط برنامه‌نویسی نرم‌افزار) مجموعه‌ای از «درخواست‌های مجاز» است که یک نرم‌افزار در اختیار نرم‌افزارهای دیگر می‌گذارد؛ مثل منوی یک رستوران. منو می‌گوید چه چیزهایی را می‌توانید سفارش دهید و هر سفارش چه اطلاعاتی لازم دارد؛ لازم نیست بدانید آشپزخانه چطور کار می‌کند.

وب‌سرویس چیست و چه فرقی با API دارد؟

وب‌سرویس نوعی API است که از راه شبکه و با پروتکل‌های وب (معمولاً HTTP) در دسترس است. پس:

هر وب‌سرویس یک API است.
اما هر API وب‌سرویس نیست؛ مثلاً توابعی که یک کتابخانهٔ نرم‌افزاری یا سیستم‌عامل در اختیار برنامه‌نویس می‌گذارد هم API هستند، بی‌آن‌که از اینترنت عبور کنند.

در دنیای پیامک، این دو اصطلاح عملاً به یک معنا به کار می‌روند: «وب‌سرویس پیامک» و «API پیامک» هر دو یعنی ارسال و دریافت پیامک با درخواست‌های اینترنتی از نرم‌افزار خودتان.

وب‌سرور با وب‌سرویس فرق دارد

وب‌سرور نرم‌افزاری است که درخواست‌های HTTP را می‌گیرد و جواب می‌دهد (مثل Nginx یا Apache). وب‌سرویس «چیزی» است که روی وب‌سرور ارائه می‌شود. وب‌سرور ساختمان است و وب‌سرویس یکی از باجه‌های داخل آن.

REST و SOAP: دو سبک ساختن وب‌سرویس

SOAP

SOAP قدیمی‌تر است: پیام‌ها در قالب XML و داخل یک «پاکت» استاندارد فرستاده می‌شوند و قرارداد سرویس معمولاً در فایلی به نام WSDL تعریف می‌شود. دقیق و رسمی است، اما حجیم‌تر است و کار با آن در زبان‌های امروزی دست‌وپاگیرتر.

REST

REST سبکی ساده‌تر است که از خود امکانات HTTP استفاده می‌کند: هر «منبع» یک نشانی دارد (مثلاً موجودی حساب یا پیام‌های دریافتی)، نوع کار را متد HTTP مشخص می‌کند و داده معمولاً JSON است.

متد	کاربرد	مثال پیامکی
GET	خواندن	گرفتن موجودی یا فهرست پیام‌های دریافتی
POST	ساختن یا انجام کار	ارسال پیامک
PUT	به‌روزرسانی	تغییر تنظیمات یک کلید API
DELETE	حذف	برداشتن یک IP از فهرست مجاز

کدام بهتر است؟

برای یک پروژهٔ تازه، تقریباً همیشه REST. سبک‌تر است، در هر زبانی با چند خط کد کار می‌کند و ابزارهای تست آن (مثل cURL یا Postman) در دسترس همه است. وب‌سرویس پیامک و درگاه پیامک (SMSGate) وب‌سرویس هم REST است.

JSON چیست؟

JSON قالبی متنی برای جابه‌جا کردن داده است که هم انسان می‌خواندش و هم ماشین. یک درخواست ارسال پیامک در قالب JSON چیزی شبیه این است:

{
  "senderNumber": "50003123",
  "recipients": ["9121234567", "9351234567"],
  "body": "سفارش شما ثبت شد."
}

آکولاد یعنی «شیء» (مجموعه‌ای از کلید و مقدار) و کروشه یعنی «فهرست». همین. چند نکتهٔ کاربردی:

متن فارسی را با کدگذاری UTF-8 بفرستید و سرآیند Content-Type: application/json را فراموش نکنید.
JSON را دستی با چسباندن رشته‌ها نسازید؛ از تابع آمادهٔ زبان‌تان استفاده کنید (json_encode در PHP یا json.dumps در پایتون) تا گیومه و کاراکترهای خاص متن پیام را خراب نکنند.

کدهای وضعیت HTTP: سرور با یک عدد جواب می‌دهد

هر پاسخ HTTP یک کد سه‌رقمی دارد که پیش از خواندن بدنه، خلاصهٔ ماجرا را می‌گوید:

2xx (موفق): کد ۲۰۰ یعنی انجام شد؛ کد ۲۰۲ یعنی «پذیرفتم و در صف گذاشتم»، که دقیقاً پاسخ درگاه پیامک به درخواست ارسال است.
4xx (اشکال از درخواست): ۴۰۰ داده نامعتبر، ۴۰۱ کلید نیامده یا نامعتبر، ۴۰۲ موجودی کافی نیست، ۴۰۳ اجازه ندارید (مثلاً IP مجاز نیست)، ۴۰۴ پیدا نشد، ۴۲۲ مقدار یکی از فیلدها پذیرفتنی نیست.
5xx (اشکال از سرور): مشکل سمت سرویس‌دهنده؛ کمی بعد دوباره تلاش کنید.

نکته: کد HTTP همهٔ داستان نیست. در وب‌سرویس ما بدنهٔ هر پاسخ قالب ثابت { code, message, data } دارد؛ code برای موفقیت ۱۰۰ است و خطاها از ۱۰۱ شروع می‌شوند، و message توضیح فارسی خطاست. برنامه‌تان را بر اساس همین code بنویسید. فهرست کامل را در «کدهای خطای وب‌سرویس پیامک» آورده‌ایم.

جمع‌بندی

وب‌سرویس یعنی API روی وب؛ REST یعنی استفادهٔ ساده از نشانی‌ها و متدهای HTTP؛ JSON قالب داده است و کد HTTP خلاصهٔ جواب. با همین چهار مفهوم می‌توانید هر مستند وب‌سرویسی را بخوانید. قدم بعدی، نوشتن اولین درخواست است: «اتصال سایت و نرم‌افزار به وب‌سرویس پیامک» را ببینید.