وب سرویس چیست و چه فرقی با REST API دارد؟ راهنمای طراحی و ساخت

وب سرویس و REST API دو واژه‌ای هستند که در پروژه‌های ایرانی مدام جای هم به کار می‌روند: «وب سرویس پیامک»، «وب سرویس استعلام»، «REST API فروشگاه». در عمل هم‌پوشانی زیادی دارند، ولی یکی نیستند — و همین تفاوت کوچک، وقتی می‌خواهید سرویس خودتان را طراحی کنید یا به سرویس کسی وصل شوید، تعیین‌کننده است. این راهنما مفاهیم را مرتب می‌کند، اصول طراحی یک REST API خوب را می‌دهد و نشان می‌دهد چطور بدون نوشتن کد سرور به یکی برسید.

وب سرویس چیست؟

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

این اصطلاح قدیمی‌تر از REST است و در ابتدا بیشتر به SOAP اشاره داشت: پیام‌های XML با ساختار سنگین و فایل توصیف WSDL. بسیاری از سرویس‌های سازمانی و بانکی در ایران هنوز از همین جنس‌اند — و دلیل اینکه واژه‌ی «وب سرویس» در فارسی این‌قدر رایج است، همین سابقه است.

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

API قرارداد است: مجموعه‌ی قواعدی که می‌گوید چطور می‌شود با یک سیستم کار کرد. هر API لزوماً روی شبکه نیست — کتابخانه‌ای که در پروژه‌تان import می‌کنید هم API دارد.

رابطه‌ی درست این است:

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

در گفت‌وگوی روزمره اگر کسی گفت «وب سرویس بدهید»، تقریباً همیشه منظورش یک REST API است که JSON برمی‌گرداند.

REST دقیقاً یعنی چه؟

REST یک پروتکل نیست؛ مجموعه‌ای از قیدهای طراحی است. چهار قید که در عمل بیشترین اثر را دارند:

• منبع‌محوری: آدرس، یک «چیز» را نشان می‌دهد نه یک «کار». /v1/product درست است، /v1/getProductList نه.
• فعل‌های HTTP: کار را متد تعیین می‌کند، نه آدرس — GET برای خواندن، POST برای ساخت، PATCH برای ویرایش جزئی، DELETE برای حذف.
• بدون حالت (stateless): هر درخواست همه‌ی چیزی که برای پردازش لازم است را با خودش می‌آورد؛ سرور بین درخواست‌ها چیزی به خاطر نمی‌سپارد. توکن در هدر می‌آید، نه در نشست سرور.
• کدهای وضعیت معنادار: ۲۰۰ موفق، ۴۰۱ ناشناس، ۴۰۴ پیدا نشد، ۴۲۲ رد شد، ۴۲۹ سقف نرخ. جواب دادن ۲۰۰ با پیام خطا داخل بدنه، رایج‌ترین اشتباه طراحی است.

REST، SOAP و GraphQL کنار هم

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

اصول طراحی یک REST API که بعداً پشیمانتان نکند

شش قاعده که تقریباً هر API خوبی رعایتشان می‌کند:

1. نام منبع، اسم است نه فعل. /v1/order نه /v1/createOrder.
2. نسخه را از اول در آدرس بگذارید. /v1/ امروز رایگان است؛ اضافه کردنش بعد از اینکه صد کلاینت وصل شدند، گران است.
3. فیلتر، مرتب‌سازی و صفحه‌بندی را از روز اول بگذارید. اولین لیستِ هزارتایی، کلاینتی را که همه‌ی رکوردها را می‌گیرد زمین می‌زند.
4. خطا را استاندارد و ماشین‌خوان کنید. یک کد پایدار برای منطق برنامه و یک متن قابل‌فهم برای انسان.
5. ویرایش جزئی باشد. PATCH فقط فیلدهای فرستاده‌شده را عوض کند؛ جایگزینی کامل، داده را بی‌سروصدا پاک می‌کند.
6. صفحه‌بندی مبتنی بر cursor را به offset ترجیح دهید. روی جدول بزرگ پایدارتر و سریع‌تر است و با درج هم‌زمان، رکورد جا نمی‌اندازد.

قالب خطای استاندارد (RFC 7807) در عمل این شکلی است:

{
  "type": "https://fikaro.ir/errors/total_must_be_positive",
  "title": "total_must_be_positive",
  "status": 422,
  "detail": "مبلغ سفارش باید بزرگ‌تر از صفر باشد",
  "code": "total_must_be_positive"
}

احراز هویت در وب سرویس

دو لایه که مدام با هم اشتباه گرفته می‌شوند:

• کلید API هویت برنامه را ثابت می‌کند. در هدر می‌آید (Authorization: Bearer ...) و هرگز نباید در کد فرانت‌اند یا مخزن عمومی برود.
• توکن کاربر (JWT) هویت کاربر نهایی را ثابت می‌کند و اجازه می‌دهد هر کاربر فقط داده‌ی خودش را ببیند.

اپلیکیشنی که فقط کلید API دارد، عملاً به همه‌ی داده دسترسی می‌دهد. تفکیک این دو لایه را در احراز هویت کاربران با JWT بدون کدنویسی کامل نوشته‌ایم.

ساخت وب سرویس بدون نوشتن کد سرور

مسیر سنتی ساخت یک REST API — فریم‌ورک، دیتابیس، لایه‌ی دسترسی، اعتبارسنجی، مستندات، دیپلوی — همان چیزی است که پلتفرم بک‌اند حذفش می‌کند. در فیکارو مدل داده را تعریف می‌کنید و اندپوینت‌های استاندارد همان لحظه فعال می‌شوند:

GET     /v1/{entity}                 # فهرست
POST    /v1/{entity}                 # ساخت
GET     /v1/{entity}/{id}            # خواندن یکی
PATCH   /v1/{entity}/{id}            # ویرایش جزئی
DELETE  /v1/{entity}/{id}            # حذف
GET     /v1/{entity}/{id}/{relation} # رکوردهای مرتبط

فیلتر، مرتب‌سازی، صفحه‌بندی cursor و روابط از همان ابتدا داخل خود API هستند:

curl "https://api.fikaro.ir/my-shop/v1/order?filter[status]=paid&sort=-created_at&include=order_item&limit=20" \
  -H "Authorization: Bearer apck_..."

جزئیات کامل عملگرها و قالب پاسخ در مستندات کار با API آمده است.

تست وب سرویس

سه ابزاری که در عمل کافی‌اند:

• curl برای بررسی سریع یک اندپوینت در ترمینال.
• Postman یا Bruno برای کالکشن و کار تیمی. هر پروژه‌ی فیکارو کالکشن آماده با سه environment می‌دهد که بعد از هر تغییر مدل داده به‌روز است (خروجی‌ها و SDK).
• Swagger/OpenAPI برای دیدن قرارداد و آزمایش زنده در مرورگر — و به‌عنوان ورودی دقیق برای تولید کد کلاینت.

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

سوالات متداول

فرق وب سرویس و API چیست؟

API مفهوم عام‌تری است: هر قراردادی که به یک برنامه اجازه کار با برنامه دیگر را می‌دهد، حتی بدون شبکه. وب سرویس زیرمجموعه آن است و از طریق شبکه فراخوانی می‌شود. در گفت‌وگوی روزمره در ایران، «وب سرویس» تقریباً همیشه یعنی یک REST API با پاسخ JSON.

REST بهتر است یا SOAP؟

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

برای ساخت وب سرویس حتماً باید برنامه‌نویس بک‌اند باشم؟

خیر. اگر سرویس شما از جنس مدیریت داده است (ساخت، خواندن، ویرایش، حذف، همراه احراز هویت)، پلتفرم‌های بک‌اند آماده همین اندپوینت‌ها را از روی مدل داده می‌سازند. کدنویسی سمت سرور فقط برای منطق واقعاً اختصاصی لازم می‌شود.

صفحه‌بندی cursor چه مزیتی به offset دارد؟

روی جدول‌های بزرگ سریع‌تر است و در برابر درج و حذف هم‌زمان پایدار می‌ماند. با offset، اگر بین دو صفحه رکورد جدیدی درج شود، ممکن است رکوردی را دو بار ببینید یا یکی را کامل از دست بدهید.