REST API، باید ها و نباید های طراحی Api

سلام به همگی! امروز می‌خوایم درمورد طراحی REST API حرف بزنیم. این مقاله رو «سید عبدالله» نوشته و در اینجا یه خلاصهٔ کاربردی ازش رو براتون آوردم، یکم همه تجربیات خودم قاطیش کردم!

---

از این مقاله چی یاد می‌گیریم؟

• اصول پایهٔ REST API چیه؟
• راهکارهای درست طراحی API چطوریه؟
• کارهای درست و غلط توی طراحی API چی هست؟

---

API چیه؟

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

APIها می‌تونن:

• خصوصی باشن (فقط برای استفادهٔ داخلی)
• شراکتی باشن (با شرکای خاص به اشتراک گذاشته بشن)
• عمومی باشن (که بقیهٔ برنامه‌نویسا بتونن برنامه‌هاشون رو بهش وصل کنن)

---

REST API چیه؟

REST API یه API هست که از قواعد و اصول «سبک معماری REST» پیروی می‌کنه. REST مخفف «representational state transfer» هست و توسط «روی فیلدینگ» ایجاد شده.

---

قواعد معماری REST

REST خودش یه پروتکل یا استاندارد نیست، بلکه یه سری قاعده و محدودیت برای طراحی هست. برای اینکه یه API واقعاً RESTful باشه، باید این قواعد رو رعایت کنه:

1. معماری کلاینت-سرور: کلاینت و سرور جدا از هم باشن و بتونن مستقل از هم توسعه پیدا کنن.
2. بدون حالت (Stateless): سرور نباید هیچ اطلاعاتی از کلاینت رو بین درخواست‌ها ذخیره کنه. هر درخواست باید مستقل باشه.
3. قابلیت کش (Cacheable): پاسخ‌ها باید قابلیت ذخیره شدن در کش رو داشته باشن تا عملکرد بهتر بشه.
4. سیستم لایه‌ای (Layered System): سرور می‌تونه چندین لایه داشته باشه (مثلاً لایهٔ امنیتی، لایهٔ داده و…) و کلاینت از این لایه‌ها خبر نداره.
5. کد بر حسب تقاضا (Code on Demand – اختیاری): سرور می‌تونه کدی (مثل جاوااسکریپت) برای اجرا در کلاینت بفرسته.
6. رابط یکنواخت (Uniform Interface): این مهم‌ترین قاعدهٔ REST هست که خودش چهار تا زیرقاعده داره:
   • شناسایی منبع در درخواست: هر منبع با یه URI مشخص می‌شه.
   • تغییر منبع از طریق بازنمایی: کلاینت با داشتن اطلاعات یه منبع، باید بتونه اون رو تغییر بده یا حذف کنه.
   • پیام‌های خود-توصیف: هر پیام باید اطلاعات کافی برای پردازش خودش رو داشته باشه.
   • هایپرمدیا به عنوان موتور حالت برنامه (HATEOAS): بعد از اولین درخواست، کلاینت باید بتونه با لینک‌هایی که سرور می‌ده، بقیهٔ مسیر رو خودش کشف کنه (مثل کلیک کردن کاربر توی یه وب‌سایت).

---

منبع (Resource) چیه و چطوری باید باشه؟

«منبع» مفهوم اصلی توی REST هست. تقریباً هر چیزی که اسم داشته باشه می‌تونه یه منبع باشه: یه عکس، یه سند، اطلاعات آب و هوا، یه محصول و…

منابع به دو دسته تقسیم می‌شن:

• تک‌منبع (Singleton): مثلاً اطلاعات یه مشتری خاص: /customers/123
• منبع مجموعه‌ای (Collection): مثلاً لیست همهٔ مشتری‌ها: /customers

همچنین یه منبع مجموعه‌ای می‌تونه زیرمجموعه هم داشته باشه:
مثلاً حساب‌های یه مشتری خاص: /customers/123/accounts

---

بهترین روش‌ها و کارهای درست و غلط

۱. از متدهای HTTP به درستی استفاده کن

• GET: برای دریافت اطلاعات.
• POST: برای ایجاد منبع جدید.
• PUT: برای جایگزینی کامل یه منبع (ایجاد یا آپدیت).
• PATCH: برای آپدیت جزئی یه منبع.
• DELETE: برای حذف یه منبع.

نکته: درخواست‌های PUT باید «تک‌بار-نتیجه» (Idempotent) باشن. یعنی اگر چند بار فرستاده بشن، نتیجه همیشه یکی باشه. اما POST و PATCH لزوماً اینطوری نیستن.

۲. از اسم (اسم جمع) برای منابع استفاده کن

منابع باید «اسم» باشن، نه «فعل»، درست مثل منابع.

✅ درست: /users, /products
❌ غلط: /getUsers, /createProduct

۳. برای روابط از زیر-منابع استفاده کن

مثلاً برای دریافت محصولات یه دسته‌بندی خاص: /categories/1/products

۴. روی خوانایی و یکنواختی تمرکز کن

• اسلش (/) آخر نشون نده:
  ✅ devices/
  ❌ /devices/
• از خط تیره (-) استفاده کن (Kebab-case):
  ✅ device-management/
  ❌ deviceManagement/ (Camel-case خوانایی کمتری داره)
• از پسوند فایل استفاده نکن:
  ✅ devices/
  ❌ devices.xml/
• اسم عملیات CRUD رو توی URI نذار:
  ✅ GET /devices
  ❌ GET /getDevices
• فعل تو URI استفاده نکن:
  ✅ POST /scripts (برای ایجاد اسکریپت جدید)
  ❌ POST /scripts/123/execute (برای اجرای اسکریپت – این یه عمل هست، نه یه منبع!)

۵. از کدهای وضعیت HTTP استفاده کن

همیشه با کدهای استاندارد HTTP به کاربر جواب بده تا بدونه درخواستش موفق بوده یا نه.

• 200:‌ موفقیت
• 201: ساخته شد
• 400: درخواست بد
• 403 : عدم دسترسی (واسه ما ایرانیا خیلی آشناست)
• 404: پیدا نشد
• 500: خطای سرور

۶. از HATEOAS برای راهنمایی کاربر استفاده کن

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

مثال:

{
  "id": 1,
  "title": "کتاب جنگ و صلح",
  "links": {
    "self": "/books/1",
    "author": "/authors/1",
    "reviews": "/books/1/reviews"
  }
}

۷. از SSL برای امنیت استفاده کن

همیشه از https استفاده کن تا ارتباطات بین کلاینت و سرور رمزگذاری بشن.

✅ https://api.com/data
❌ http://api.com/data

۸. مستندات دقیق ارائه بده

مستندات خوب، کلید موفقیت یه API هست. از ابزارهایی مثل OpenAPI (Swagger) برای ساخت مستندات تمیز و قابل درک استفاده کن.

۹. امنیت و کنترل دسترسی رو فراموش نکن

• از OAuth 2.0 یا JWT برای احراز هویت استفاده کن.
• محدودیت نرخ درخواست (Rate Limiting) اعمال کن تا از سوءاستفاده جلوگیری بشه.
• از کنترل دسترسی بر اساس نقش (RBAC) استفاده کن.

۱۰. به عملکرد (Performance) API توجه کن

• از کش استفاده کن.
• داده‌ها رو فشرده کن (مثلاً با GZIP).
• پردازش‌های ناهمزمان (Async) داشته باش.
• APIت رو تست کن: تست واحد، تست یکپارچگی، تست بار و تست امنیت.

---

نتیجه‌گیری

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

امیدوارم این راهنما برات مفید بوده باشه. موفق باشی!