REST API Design Rulebook

1. APIهای REST از قابلیت‌های کامل HTTP برای ارتباط وب مقیاس‌پذیر بهره می‌برند

REST به ما می‌گوید که چگونه وب به مقیاس بزرگ خود دست یافته است.

محدودیت‌های معماری مقیاس‌پذیری را ممکن می‌سازند. REST (انتقال حالت نمایشی) سبک معماری وب جهانی است که برای دستیابی به مقیاس‌پذیری عظیم طراحی شده است. این هدف را از طریق محدودیت‌های کلیدی زیر محقق می‌کند:

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

این محدودیت‌ها با هم کار می‌کنند تا سیستمی توزیع‌شده ایجاد کنند که قادر به مدیریت تعداد زیادی از تعاملات باشد و در عین حال انعطاف‌پذیر و کارا باقی بماند.

2. URIها باید منابع را به‌طور منحصربه‌فرد شناسایی کنند بدون اینکه جزئیات پیاده‌سازی را فاش کنند

هر کاراکتر درون یک URI به هویت منحصربه‌فرد یک منبع کمک می‌کند.

طراحی URIهای شفاف و سلسله‌مراتبی. URIها (شناسه‌های منبع یکنواخت) اساس APIهای REST هستند که هر منبع را به‌طور منحصربه‌فرد شناسایی می‌کنند. بهترین شیوه‌ها برای طراحی URI شامل موارد زیر است:

• استفاده از اسلش‌های رو به جلو برای نشان دادن روابط سلسله‌مراتبی
• ترجیح حروف کوچک
• استفاده از خط تیره برای بهبود خوانایی
• اجتناب از پسوندهای فایل
• استفاده از اسامی جمع برای مجموعه‌ها
• استفاده از اسامی مفرد برای منابع خاص
• استفاده از نام‌گذاری‌های سازگار در سراسر API

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

3. روش‌های HTTP تعاملات استاندارد با منابع را تعریف می‌کنند

یک API REST نباید طراحی خود را با استفاده نادرست از روش‌های درخواست HTTP برای تطبیق با کلاینت‌هایی با واژگان محدود HTTP به خطر بیندازد.

استفاده سازگار از روش‌های HTTP. روش‌های استاندارد HTTP یک رابط یکنواخت برای تعامل با منابع فراهم می‌کنند:

• GET: بازیابی نمایش یک منبع
• POST: ایجاد یک منبع جدید در یک مجموعه یا اجرای یک کنترلر
• PUT: به‌روزرسانی یک منبع موجود یا ایجاد یک منبع جدید در یک فروشگاه
• DELETE: حذف یک منبع
• HEAD: بازیابی متاداده درباره یک منبع
• OPTIONS: کشف تعاملات موجود برای یک منبع

هر روش دارای معنای خاص و رفتار مورد انتظار است. به‌عنوان مثال، GET باید ایمن و ایدم‌پوتنت باشد، در حالی که POST ممکن است اثرات جانبی داشته باشد. استفاده سازگار از این روش‌ها در طراحی API شما پیش‌بینی‌پذیری و قابلیت همکاری را افزایش می‌دهد.

4. متاداده در هدرهای HTTP عملکرد و کارایی API را بهبود می‌بخشد

کش یکی از مفیدترین ویژگی‌های ساخته‌شده بر روی HTTP است.

استفاده از هدرهای HTTP برای متاداده. هدرهای HTTP عملکرد زیادی برای APIهای REST فراهم می‌کنند:

• Content-Type: نوع رسانه بدنه درخواست یا پاسخ را مشخص می‌کند
• ETag: امکان کش کارآمد و درخواست‌های شرطی را فراهم می‌کند
• Cache-Control: رفتار کش را برای بهبود عملکرد هدایت می‌کند
• Authorization: از طرح‌های مختلف احراز هویت پشتیبانی می‌کند
• Accept: امکان مذاکره محتوا برای نمایش‌های مختلف را فراهم می‌کند

استفاده صحیح از هدرها می‌تواند به‌طور قابل‌توجهی عملکرد، امنیت و انعطاف‌پذیری API را بهبود بخشد. به‌عنوان مثال، استفاده مؤثر از هدرهای کش می‌تواند بار سرور را کاهش داده و زمان پاسخ را بهبود بخشد، در حالی که هدرهای احراز هویت امکان کنترل دسترسی امن را فراهم می‌کنند.

5. نمایش‌های منابع باید از فرمت‌های سازگار و کنترل‌های هایپرمدیا استفاده کنند

کلاینت‌های API REST باید تشویق شوند که به ویژگی‌های خودتوصیفی یک API REST تکیه کنند.

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

• استفاده از فرمت‌های استاندارد مانند JSON یا XML
• شامل کنترل‌های هایپرمدیا (لینک‌ها) برای راهنمایی کلاینت‌ها در اقدامات موجود
• استفاده از ساختارهای سازگار برای عناصر مشترک مانند خطاها
• استفاده از نام‌های فیلد توصیفی و انواع داده مناسب
• شامل متاداده درباره نمایش (مثلاً اطلاعات طرح)

کنترل‌های هایپرمدیا به‌ویژه مهم هستند، زیرا به API اجازه می‌دهند کلاینت‌ها را در حالت برنامه راهنمایی کنند. این امر امکان اتصال ضعیف‌تر بین کلاینت‌ها و سرورها را فراهم می‌کند و قابلیت تکامل API را بهبود می‌بخشد.

6. استراتژی‌های نسخه‌بندی، امنیت و ترکیب‌پذیری انعطاف‌پذیری API را بهبود می‌بخشند

OAuth یک پروتکل احراز هویت مبتنی بر HTTP است که امکان حفاظت از منابع را فراهم می‌کند.

طراحی برای تکامل و امنیت. استراتژی‌های کلیدی برای APIهای انعطاف‌پذیر و امن شامل موارد زیر است:

• نسخه‌بندی: استفاده از نسخه‌بندی طرح به‌جای نسخه‌بندی URI
• امنیت: پیاده‌سازی OAuth یا راه‌حل‌های مدیریت API برای کنترل دسترسی
• پاسخ‌های جزئی: اجازه به کلاینت‌ها برای درخواست فقط فیلدهای مورد نیاز
• منابع جاسازی‌شده: امکان بازیابی منابع مرتبط در یک درخواست
• مدیریت خطا: ارائه پاسخ‌های خطای سازگار و اطلاعاتی

این استراتژی‌ها به APIها اجازه می‌دهند با گذشت زمان بدون شکستن کلاینت‌های موجود تکامل یابند و در عین حال ویژگی‌های امنیتی و کارایی مورد نیاز برنامه‌های مدرن را فراهم کنند.

7. کلاینت‌های جاوااسکریپت نیاز به ملاحظات ویژه برای درخواست‌های بین‌مبدأ دارند

CORS جایگزینی برای JSONP است که از همه روش‌های درخواست پشتیبانی می‌کند.

فعال‌سازی دسترسی بین‌مبدأ. محدودیت‌های امنیتی مرورگر می‌تواند چالش‌هایی برای کلاینت‌های جاوااسکریپت که به APIها از دامنه‌های مختلف دسترسی دارند ایجاد کند. دو رویکرد اصلی به این مسئله می‌پردازند:

• JSONP (JSON با پدینگ): امکان دسترسی فقط خواندنی با بهره‌گیری از رفتار تگ اسکریپت
• CORS (اشتراک منابع بین‌مبدأ): فراهم کردن دسترسی کامل خواندن/نوشتن با پشتیبانی مرورگر

CORS رویکردی قوی‌تر و استانداردتر است که از همه روش‌های HTTP پشتیبانی می‌کند. با پیاده‌سازی CORS، APIها می‌توانند به‌طور امن دسترسی از برنامه‌های جاوااسکریپت میزبانی‌شده در دامنه‌های مختلف را فراهم کنند و برنامه‌های وب غنی و ترکیبی را ممکن سازند.

آخرین به‌روزرسانی:: September 5, 2024