REST API چیست؟

در یکی از پروژه‌های یکپارچه‌سازی که سال گذشته روی آن کار می‌کردم، تیم فنی یک شرکت بزرگ بیمه با مشکل جدی روبرو بود: سیستم مدیریت مشتریان، سیستم صدور بیمه‌نامه و اپلیکیشن موبایل، هر سه با یکدیگر ارتباط برقرار می‌کردند، اما هر بار که یک تغییر کوچک در یکی از سرویس‌ها اتفاق می‌افتاد، بقیه سرویس‌ها از کار می‌افتادند. ریشه مشکل، نبود یک معماری استاندارد برای ارتباط بین سرویس‌ها بود. این دقیقاً همان جایی است که REST API (Representational State Transfer Application Programming Interface) به عنوان یک راه‌حل بالغ و استاندارد مطرح می‌شود. در این مقاله، بر اساس تجربه‌های عملی و مطالعه مستقیم پایان‌نامه دکترای روی فیلدینگ در سال ۲۰۰۰ که معماری REST را معرفی کرد، این مفهوم را در عمق بررسی می‌کنم.

در ۲۰۲۶، بیش از ۸۳ درصد از APIهای عمومی در وب، از معماری REST پیروی می‌کنند. طبق گزارش Postman State of the API، حدود ۸۹ درصد از توسعه‌دهندگان به طور منظم با REST API کار می‌کنند و این معماری همچنان به عنوان پایه اصلی ارتباطات سرویس‌محور باقی مانده است. با وجود ظهور GraphQL و gRPC، REST به دلیل سادگی، سازگاری با HTTP و ابزارهای بالغ، همچنان انتخاب اول اکثر پروژه‌هاست. اما استفاده از REST و درک صحیح REST، دو چیز متفاوت هستند که در این مقاله به تفکیک بررسی می‌شوند.

REST API در یک تعریف دقیق

REST (Representational State Transfer) یک سبک معماری (Architectural Style) برای طراحی سیستم‌های توزیع‌شده است، نه یک پروتکل یا استاندارد صلب. این تفکیک بسیار مهم است، چون بسیاری از توسعه‌دهندگان به اشتباه REST را با HTTP اشتباه می‌گیرند. REST یک سری اصول و محدودیت‌ها را تعریف می‌کند که اگر رعایت شوند، سیستم حاصل، ویژگی‌های مشخصی مثل مقیاس‌پذیری، سادگی و قابلیت تکامل خواهد داشت. اما خود REST وابسته به پروتکل خاصی نیست، هرچند در عمل، پیاده‌سازی REST بر بستر HTTP رایج‌ترین حالت است.

API (Application Programming Interface) به معنای واسط برنامه‌نویسی است، یعنی مجموعه قواعدی که به یک برنامه اجازه می‌دهد با برنامه دیگر صحبت کند. REST API یعنی APIای که بر اساس اصول معماری REST طراحی شده. اگر با مفاهیم پایه‌ای API آشنا نیستید، پیشنهاد می‌کنم ابتدا API چیست و چه کاربردی دارد را مطالعه کنید. همچنین اگر می‌خواهید تفاوت REST با سایر سبک‌های معماری API را ببینید، اصطلاح API چیست و REST از پایه تا طراحی حرفه‌ای را بخوانید.

از منظر مهندسی، REST API را می‌توان به عنوان یک قرارداد ارتباطی در نظر گرفت که بر اساس منابع (Resources) و عملیات روی آن‌ها بنا شده است. در این مدل، هر چیزی که از بیرون قابل دسترسی است، یک منبع است: کاربر، محصول، سفارش، دسته‌بندی، تصویر و... . هر منبع یک شناسه یکتا (مثل URL) دارد و از طریق متدهای استاندارد HTTP قابل دستکاری است.

تاریخچه و ریشه معماری REST

REST توسط روی فیلدینگ (Roy Fielding) در پایان‌نامه دکترای خود در دانشگاه کالیفرنیا ارواین در سال ۲۰۰۰ معرفی شد. فیلدینگ یکی از نویسندگان اصلی پروتکل HTTP/1.1 بود و پایان‌نامه‌اش، تلفیقی از تجربه عملی او در طراحی HTTP و نظریه معماری نرم‌افزار بود. عنوان پایان‌نامه او، Architectural Styles and the Design of Network-based Software Architectures بود که به عنوان مرجع اصلی REST در نظر گرفته می‌شود.

در آن پایان‌نامه، فیلدینگ استدلال کرد که وب با یک سری محدودیت‌های مشخص کار می‌کند و همین محدودیت‌ها باعث موفقیت آن شده‌اند. REST در واقع تلاش برای استخراج و صوری‌سازی همان محدودیت‌هاست. اگر می‌خواهید با مفاهیم عمیق‌تر آشنا شوید، مفهوم REST (Representational State Transfer) در ویکی‌پدیا به شکل جامعی توضیح داده شده است.

پذیرش REST در دهه ۲۰۰۰ به سرعت رشد کرد، به ویژه با ظهور شرکت‌هایی مثل Twitter، Amazon و Google که APIهای عمومی خود را بر اساس REST طراحی کردند. در دهه ۲۰۱۰، REST به استاندارد عملی صنعت تبدیل شد و ابزارهایی مثل Swagger، Postman و OpenAPI برای مستندسازی و تست آن شکل گرفتند. در سال‌های اخیر، با ظهور GraphQL و gRPC، بحث‌هایی درباره آینده REST مطرح شده، اما این معماری همچنان در ۲۰۲۶ یکی از ستون‌های اصلی ارتباط بین سرویس‌هاست.

شش محدودیت اصلی معماری REST

REST بر شش محدودیت بنیادین استوار است که در پایان‌نامه فیلدینگ تعریف شده‌اند. رعایت این محدودیت‌ها، ویژگی‌های مطلوب سیستم را تضمین می‌کند.

محدودیت اول، Client-Server: جداسازی کامل کلاینت از سرور. کلاینت فقط با API صحبت می‌کند و از جزئیات پیاده‌سازی سرور بی‌خبر است. این جداسازی، به تیم‌های مختلف اجازه می‌دهد مستقل توسعه دهند و هر سمت بتواند بدون تأثیر بر دیگری تغییر کند. اگر با معماری وب آشنا نیستید، معماری وب چیست چارچوب مناسبی ارائه می‌دهد.

محدودیت دوم، Stateless: هر درخواست باید همه اطلاعات لازم برای پردازش را با خود داشته باشد. سرور نباید وضعیت قبلی کاربر را بین درخواست‌ها نگه دارد. این محدودیت، امکان مقیاس‌پذیری افقی را فراهم می‌کند، چون هر سرور می‌تواند هر درخواستی را مستقل پردازش کند. این موضوع در اصول طراحی معماری وب مدرن به تفصیل بررسی شده است.

محدودیت سوم، Cacheable: پاسخ‌ها باید به صراحت قابل کش یا غیرقابل کش اعلام شوند. این محدودیت، به کاهش بار سرور و بهبود سرعت کمک می‌کند. در REST، از هدرهای Cache-Control، ETag و Last-Modified برای مدیریت کش استفاده می‌شود.

محدودیت چهارم، Uniform Interface: این محدودیت، شاید مهم‌ترین و در عین حال مبهم‌ترین محدودیت REST است. یعنی همه منابع باید از طریق یک رابط یکسان قابل دسترسی باشند. Uniform Interface خود چهار زیرمجموعه دارد: شناسایی منابع از طریق URL، دستکاری منابع از طریق نمایش‌ها، پیام‌های خودتوصیف و HATEOAS (Hypermedia As The Engine Of Application State).

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

محدودیت ششم، Code on Demand: این محدودیت اختیاری است و اجازه می‌دهد سرور کد اجرایی (مثل JavaScript) به کلاینت ارسال کند. این محدودیت در عمل کمتر رعایت می‌شود، چون امنیت و سازگاری را پیچیده می‌کند.

REST یک سبک معماری است، نه یک استاندارد. اگر سیستمی این شش محدودیت را رعایت کند، RESTful است؛ اگر فقط بعضی را رعایت کند، REST-like است. تفاوت این دو، در تولید، ملموس است.

متدهای HTTP و معنای آن‌ها

متدهای HTTP، فعل‌های REST هستند. هر متد یک معنای مشخص دارد و بر اساس اصول HTTP/1.1 تعریف شده. در REST، این معناها باید رعایت شوند تا API قابل پیش‌بینی باشد.

مفهوم Idempotent (تکرارپذیر) یعنی اگر یک درخواست را چند بار بفرستید، اثرش مانند یک بار فرستادن است. مفهوم Safe (ایمن) یعنی درخواست نباید وضعیت سرور را تغییر دهد. این دو مفهوم، در طراحی API پایدار بسیار مهم هستند، چون در شرایط شبکه‌ای ناپایدار، کلاینت ممکن است مجبور شود درخواست را تکرار کند.

یک اشتباه رایج در پیاده‌سازی REST: استفاده از GET برای انجام عملیات تغییردهنده. مثلاً GET /users/delete/123. این اشتباه، می‌تواند باعث مشکلات جدی شود، چون GET ممکن است توسط Crawler یا Cache سیستم‌ها بدون اطلاع کاربر فراخوانی شود. اگر با مفاهیم پایه‌ای HTTP آشنا نیستید، REST از پایه تا طراحی حرفه‌ای و آموزش REST API را مطالعه کنید.

کدهای وضعیت HTTP

کدهای وضعیت (Status Codes) HTTP، پاسخ سرور به کلاینت را توصیف می‌کنند. در REST، استفاده صحیح این کدها، بخشی جدانشدنی از طراحی خوب است. کدهای HTTP به پنج دسته تقسیم می‌شوند: ۱xx (اطلاعاتی)، ۲xx (موفق)، ۳xx (ریدایرکت)، ۴xx (خطای کلاینت)، ۵xx (خطای سرور).

یکی از نکات کلیدی در طراحی REST API، تفکیک دقیق 401 و 403 است. کد 401 به این معناست که کلاینت احراز هویت نشده و باید اول احراز هویت کند. کد 403 یعنی کلاینت احراز هویت شده اما مجوز دسترسی به منبع مورد نظر را ندارد. این تفکیک، در فرآیند عیب‌یابی و امنیت بسیار مهم است.

کد 422 (Unprocessable Entity) یک کد نسبتاً جدیدتر است که در RFC 4918 تعریف شده و برای اعلام خطاهای اعتبارسنجی استفاده می‌شود. به جای استفاده از 400 برای همه خطاهای کلاینت، استفاده از 422 برای خطاهای منطقی اعتبارسنجی، طراحی API را دقیق‌تر می‌کند.

منابع و نام‌گذاری آن‌ها

در REST، همه چیز یک منبع (Resource) است. منبع، یک موجودیت قابل دسترسی است که با یک شناسه یکتا (معمولاً URL) مشخص می‌شود. طراحی درست منابع و URLها، پایه یک API خوب است.

اصول نام‌گذاری منابع در REST: اول، از اسم جمع استفاده کنید، نه فعل. مثلاً /users، نه /getUsers. دوم، از اسم مفرد برای منابع منفرد استفاده کنید، مثل /users/123. سوم، از ساختار سلسله‌مراتبی برای روابط استفاده کنید، مثل /users/123/orders. چهارم، از خط تیره (hyphen) به جای زیرخط (underscore) در URL استفاده کنید. پنجم، از حروف کوچک استفاده کنید.

نمونه‌های درست و نادرست نام‌گذاری:

درست:
GET    /users
GET    /users/123
GET    /users/123/orders
POST   /users
PUT    /users/123
DELETE /users/123

نادرست:
GET    /getUsers
GET    /user/123
POST   /createUser
POST   /deleteUser/123
GET    /users_list

نکته مهم درباره منابع تودرتو: اگر روابط سلسله‌مراتبی بیش از دو سطح بشوند، معمولاً بهتر است از منابع جداگانه استفاده کنید. مثلاً /users/123/orders/456/items/789 خیلی پیچیده است و بهتر است /orders/456/items استفاده شود. تعادل بین سادگی و بیان روابط، یک تصمیم طراحی است.

بی‌حالتی و مدیریت وضعیت

Stateless بودن یکی از بنیادین‌ترین محدودیت‌های REST است که در عمل چالش‌های متعددی ایجاد می‌کند. Stateless یعنی سرور نباید هیچ وضعیتی از کلاینت را بین درخواست‌ها نگه دارد. هر درخواست باید همه اطلاعات لازم برای پردازش را شامل شود: احراز هویت، مجوزدهی، پارامترها و هر چیز دیگر.

چرا Stateless اهمیت دارد؟ دلیل اصلی، مقیاس‌پذیری است. اگر سرور وضعیت کاربر را نگه دارد، برای مقیاس‌پذیری افقی باید بین سرورها همگام‌سازی شود که پیچیدگی را به شدت افزایش می‌دهد. در یک سیستم Stateless، هر سرور می‌تواند هر درخواستی را بدون نیاز به هماهنگی پردازش کند.

در عمل، پیاده‌سازی Stateless در REST نیازمند مکانیزم‌هایی مثل JWT (JSON Web Token)، API Key و OAuth 2.0 است. JWT اطلاعات احراز هویت و مجوز را در خود توکن کدگذاری می‌کند. این رویکرد، به سرور اجازه می‌دهد بدون ذخیره وضعیت، هر درخواست را مستقل پردازش کند. اگر با JWT آشنا نیستید، JWT چیست و چه کاربردی در احراز هویت دارد را مطالعه کنید. احراز هویت در REST API به طور کامل در احراز هویت در REST API بررسی شده است.

نمایش‌ها و فرمت‌های داده

در REST، منبع با نمایش (Representation) آن فرق دارد. منبع، موجودیت ذهنی است. نمایش، فرمت مشخصی است که منبع در آن منتقل می‌شود: JSON، XML، HTML، YAML یا هر فرمت دیگر. کلاینت در Content Negotiation از طریق هدر Accept اعلام می‌کند که چه فرمتی می‌خواهد.

JSON (JavaScript Object Notation) در ۲۰۲۶ رایج‌ترین فرمت برای REST APIهاست. طبق آمار، بیش از ۹۵ درصد از REST APIهای عمومی از JSON استفاده می‌کنند. دلایل این محبوبیت: خوانا برای انسان، سبک، پارس سریع، و پشتیبانی بومی در JavaScript. اگر با JSON آشنا نیستید، JSON چیست و چگونه داده‌ها را ساختاردهی می‌کند و کار با JSON در پروژه‌های واقعی را بخوانید.

یک مثال از JSON در REST API:

{
  "id": 123,
  "name": "محمد رضایی",
  "email": "mohammad@example.com",
  "roles": ["admin", "editor"],
  "created_at": "2026-01-15T10:30:00Z"
}

ساختار JSON باید یکنواخت باشد. یعنی همه فیلدها با یک قاعده نام‌گذاری (snake_case یا camelCase) نوشته شوند و ساختار خطاها هم استاندارد باشد. یکی از استانداردهای مهم در این حوزه، RFC 7807 است که فرمت Problem Details for HTTP APIs را تعریف می‌کند.

HATEOAS و بلوغ REST

HATEOAS (Hypermedia As The Engine Of Application State) پیشرفته‌ترین و در عین حال کم‌استفاده‌ترین جنبه REST است. این مفهوم می‌گوید که سرور، در پاسخ‌ها، لینک‌هایی به اقدامات ممکن در وضعیت فعلی ارائه می‌دهد. کلاینت با دنبال کردن این لینک‌ها، از وضعیت فعلی به وضعیت بعدی می‌رود.

نمونه یک پاسخ با HATEOAS:

{
  "id": 123,
  "name": "سفارش شماره ۱۲۳",
  "status": "pending",
  "total": 250000,
  "_links": {
    "self": { "href": "/orders/123" },
    "cancel": { "href": "/orders/123/cancel", "method": "POST" },
    "pay": { "href": "/orders/123/payment", "method": "POST" },
    "customer": { "href": "/users/456" }
  }
}

مدل بلوغ Richardson (Richardson Maturity Model) چهار سطح بلوغ REST را تعریف می‌کند. سطح صفر: استفاده از HTTP به عنوان تونل. سطح یک: معرفی منابع. سطح دو: استفاده از متدهای HTTP. سطح سه: HATEOAS. اکثر APIهای امروز در سطح دو هستند. سطح سه، در عمل کمتر رعایت می‌شود چون پیچیدگی کلاینت را افزایش می‌دهد.

اما HATEOAS مزایای جدی دارد: کلاینت‌ها می‌توانند بدون دانستن از قبل، با API کار کنند، قابلیت کشف (Discovery) فراهم می‌شود، و API می‌تواند بدون شکستن کلاینت‌ها تکامل یابد. برای پروژه‌های سازمانی که APIهای طولانی‌مدت دارند، HATEOAS یک سرمایه‌گذاری منطقی است. اگر به طراحی API علاقه‌مندید، اصول طراحی REST API را مطالعه کنید.

پیاده‌سازی در عمل

پیاده‌سازی REST API در زبان‌های مختلف، الگوهای مشترکی دارد. در PHP، فریمورک‌هایی مثل Laravel و Symfony ابزارهای جامعی ارائه می‌دهند. در Python، فریمورک‌هایی مثل Django REST Framework و FastAPI. در Node.js، Express و NestJS. اگر می‌خواهید با پیاده‌سازی آشنا شوید، ساخت API با PHP و ساخت REST API با پایتون را ببینید.

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

مراحل پیاده‌سازی یک REST API حرفه‌ای: اول، طراحی منابع و URLها. دوم، انتخاب متدهای HTTP مناسب. سوم، طراحی فرمت پاسخ‌ها (موفق و خطا). چهارم، پیاده‌سازی احراز هویت و مجوزدهی. پنجم، پیاده‌سازی محدودیت نرخ (Rate Limiting). ششم، پیاده‌سازی کش. هفتم، مستندسازی با OpenAPI یا Swagger. مباحث مستندسازی در راهنمای مستندسازی API و مستندسازی REST API با Swagger بررسی شده است.

آزمایش و تست REST API بخش جدانشدنی پیاده‌سازی است. ابزارهایی مثل Postman، Insomnia و curl برای تست دستی، و فریمورک‌هایی مثل Pest، PHPUnit و pytest برای تست خودکار. اگر به این حوزه علاقه‌مندید، تست REST API با Postman و آموزش تست API را ببینید.

پرسش‌های پرتکرار درباره REST API

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

تفاوت REST و RESTful چیست؟ REST یک سبک معماری است و RESTful یک صفت برای سیستم‌هایی است که این سبک را رعایت می‌کنند. اگر سیستمی همه محدودیت‌های REST را رعایت کند، RESTful است. در عمل، اکثر APIها فقط بعضی از این محدودیت‌ها را رعایت می‌کنند و REST-like نامیده می‌شوند.

آیا REST منسوخ شده است؟ خیر. با وجود ظهور GraphQL و gRPC، REST همچنان در ۲۰۲۶ انتخاب اول اکثر پروژه‌هاست. طبق گزارش Postman، بیش از ۸۳ درصد از APIهای عمومی از REST استفاده می‌کنند. هر سبک معماری، نقاط قوت و ضعف خودش را دارد و انتخاب باید بر اساس نیاز پروژه باشد.

چه زمانی از REST استفاده نکنم؟ در سه حالت: اول، وقتی کلاینت به دیتای بسیار به‌هم‌پیوسته و تودرتو نیاز دارد (GraphQL بهتر است). دوم، وقتی کارایی در سطح میلی‌ثانیه حیاتی است و پروتکل‌های باینری کارآمدترند (gRPC بهتر است). سوم، وقتی ارتباط بلادرنگ نیاز است (WebSocket بهتر است).

چگونه REST API را امن کنم؟ سه لایه اصلی: احراز هویت با OAuth 2.0 یا JWT، مجوزدهی مبتنی بر نقش یا Scope، و محافظت در برابر حملات رایج مثل SQL Injection، XSS و CSRF. اصول امنیت API در چگونه REST API امن بسازیم و امنیت API بررسی شده است.

آیا REST API نیاز به نسخه‌بندی دارد؟ بله، در عمل لازم است. سه رویکرد رایج: نسخه در URL مثل /v1/users، نسخه در هدر مثل Accept: application/vnd.api.v1+json، و نسخه در پارامتر مثل /users?version=1. رویکرد اول ساده‌تر و رایج‌تر است. مباحث بیشتر در نسخه‌بندی REST API آمده است.

چگونه کارایی REST API را بهبود دهم؟ چند استراتژی کلیدی: کش با ETag و Cache-Control، Pagination برای مجموعه‌های بزرگ، Compression با gzip یا brotli، انتخاب فیلدهای مورد نیاز با فیلدسلکتور، و بهینه‌سازی کوئری‌های دیتابیس. مباحث بیشتر در بهینه‌سازی عملکرد REST API و اشتباهات رایج در REST API بررسی شده است.

آنچه باید با خود ببرید

REST API یک سبک معماری برای طراحی سیستم‌های توزیع‌شده است که بر شش محدودیت بنیادین استوار است: Client-Server، Stateless، Cacheable، Uniform Interface، Layered System و Code on Demand. رعایت این محدودیت‌ها، ویژگی‌های مطلوبی مثل مقیاس‌پذیری، سادگی و قابلیت تکامل را تضمین می‌کند.

پنج اصل کلیدی که در این مقاله بررسی شد:

1. REST یک سبک معماری است، نه یک پروتکل؛ و HTTP بستر طبیعی آن است.
2. شش محدودیت REST، پایه طراحی‌های مقیاس‌پذیر و قابل تکامل هستند.
3. استفاده درست از متدهای HTTP و کدهای وضعیت، بخشی جدانشدنی از REST حرفه‌ای است.
4. بی‌حالتی، کلید مقیاس‌پذیری افقی است و با JWT یا OAuth پیاده می‌شود.
5. HATEOAS سطح بلوغ بالای REST است که در پروژه‌های بلندمدت ارزش سرمایه‌گذاری دارد.

قدم عملی امروز: اگر پروژه‌ای با REST API دارید، سه URL را بررسی کنید و ببینید آیا از اصول نام‌گذاری منابع پیروی می‌کنند یا خیر. سپس بررسی کنید که در کد وضعیت 401 و 403 تفکیک درست انجام شده یا خیر. این دو بررسی، ساده اما نشان‌دهنده کیفیت API شماست.

اگر تجربه‌ای در طراحی یا استفاده از REST API در پروژه‌های واقعی داشتید — به‌خصوص اگر با چالش خاصی مثل HATEOAS یا نسخه‌بندی مواجه شده‌اید — در دیدگاه‌ها بنویسید. این تجربه‌ها برای خواننده‌های بعدی بسیار ارزشمند خواهند بود. 🌐