طراحی معماری API

منظور از API Architectural Design (طراحی معماری API)، نحوه‌ی سازمان‌دهی، ساختاردهی و ارتباط سرویس‌هاست. این انتخاب‌ها روی کارایی، مقیاس‌پذیری، امنیت و تجربه توسعه‌دهنده تأثیر مستقیم می‌گذاره.

معماری‌های مختلف برای API وجود داره که هر کدوم مزایا، معایب و سناریوهای استفاده‌ی خودشون رو دارن.

مدل‌های رایج معماری API

1. REST (Representational State Transfer)

• محبوب‌ترین معماری API.
• از HTTP به عنوان پروتکل استفاده می‌کنه.
• هر منبع (resource) یک URL مشخص داره.
• عملیات CRUD با متدهای HTTP (GET, POST, PUT, DELETE).

مثال:

GET /users        → دریافت لیست کاربران
GET /users/15     → دریافت کاربر با شناسه 15
POST /users       → ایجاد کاربر جدید
PUT /users/15     → ویرایش کاربر 15
DELETE /users/15  → حذف کاربر 15

مزایا: ساده، مقیاس‌پذیر، پشتیبانی گسترده
معایب: بعضی وقت‌ها داده بیش‌ازحد (Over-fetching) یا کمتر از نیاز (Under-fetching) ارسال می‌شود.

2. SOAP (Simple Object Access Protocol)

• معماری قدیمی‌تر، مبتنی بر XML.
• معمولا در سیستم‌های سازمانی (Enterprise) و سرویس‌های بانکی/مالی استفاده می‌شود.
• دارای استانداردهای امنیتی قوی (WS-Security).

مثال:

<soap:Envelope>
   <soap:Body>
      <GetUser>
         <UserId>15</UserId>
      </GetUser>
   </soap:Body>
</soap:Envelope>

مزایا: امنیت و استاندارد بالا، مناسب برای تراکنش‌های حساس
معایب: سنگین‌تر از REST، توسعه سخت‌تر

3. GraphQL

• توسط Facebook معرفی شد.
• به کلاینت اجازه می‌ده دقیقا داده‌ی موردنیازش رو درخواست کنه.
• یک Endpoint واحد داره (برخلاف REST).

مثال:

query {
  user(id: 15) {
    id
    name
    posts {
      title
    }
  }
}

اینجا فقط id, name و title پست‌ها برگردونده می‌شه.

مزایا: جلوگیری از over-fetching و under-fetching
معایب: پیچیدگی بیشتر در پیاده‌سازی و caching

4. gRPC (Google Remote Procedure Call)

• توسط Google توسعه داده شده.
• از پروتکل HTTP/2 و Protocol Buffers (Protobuf) برای serialization استفاده می‌کنه.
• بسیار سریع و سبک، مناسب برای ارتباط سرویس‌به‌سرویس (Microservices).

مثال:

service UserService {
  rpc GetUser (UserRequest) returns (UserResponse);
}

در سمت کلاینت صدا زده می‌شه:

const user = client.GetUser({ id: 15 });

مزایا: سرعت بالا، مناسب برای real-time و میکروسرویس‌ها
معایب: یادگیری سخت‌تر، ابزارهای کمتر نسبت به REST

5. WebSockets API

• برای ارتباط دوطرفه و real-time (مانند چت، بازی آنلاین).
• کلاینت و سرور می‌تونن در هر لحظه پیام ارسال کنند.

مثال:

const socket = new WebSocket("ws://example.com/chat");

socket.onopen = () => socket.send("سلام 👋");
socket.onmessage = (event) => console.log("پیام:", event.data);

مزایا: ارتباط زنده و سریع
معایب: مناسب برای CRUD یا API سنتی نیست

6. Server-Sent Events (SSE)

• یک ارتباط یک‌طرفه از سرور به کلاینت.
• مناسب برای استریم داده مثل قیمت لحظه‌ای بورس.

مثال:

const eventSource = new EventSource("/prices");
eventSource.onmessage = (e) => console.log(e.data);

مقایسه کاربردی معماری‌های API

1. REST

• کجا استفاده کنیم؟
  • اپلیکیشن‌های عمومی (وب/موبایل)
  • پروژه‌هایی که نیاز به API ساده دارن
  • وقتی که ابزارها و کتابخانه‌های آماده زیادی می‌خوایم
• مثال:
  رزرو هتل یا رستوران → کاربر بتونه لیست اتاق‌ها یا میزها رو ببینه، رزرو کنه، و تاریخچه رزرو رو دریافت کنه.

2. SOAP

• کجا استفاده کنیم؟
  • سیستم‌های بانکی و مالی
  • اپلیکیشن‌های Enterprise که نیاز به امنیت و تراکنش مطمئن دارن
  • جاهایی که استانداردها (WS-Security, WS-ReliableMessaging) ضروریه
• مثال:
  انتقال وجه بین بانکی یا خرید بلیط هواپیما که تراکنش نباید وسط راه قطع بشه.

3. GraphQL

• کجا استفاده کنیم؟
  • اپلیکیشن‌هایی که فرانت‌اند موبایل یا وب دارن و نیاز به داده‌های خیلی دقیق دارن
  • زمانی که REST داده‌های اضافی زیادی برمی‌گردونه یا کافی نیست
  • وقتی که نیاز به جمع‌آوری داده از چند سرویس مختلف داریم
• مثال:
  اپلیکیشن رزرو رستوران → کاربر فقط اسم رستوران + آدرس + ساعت آزاد رو بخواد، نه کل دیتابیس منو و عکس‌ها.

4. gRPC

• کجا استفاده کنیم؟
  • معماری‌های Microservices
  • سرویس‌هایی که به سرعت بالا نیاز دارن (Streaming, IoT, Realtime)
  • ارتباط سرویس به سرویس (Backend-to-Backend)
• مثال:
  در یک سیستم رزرواسیون بزرگ، سرویس «پرداخت» با سرویس «رزرو» و «اعلان پیامک» با سرعت بالا ارتباط بگیره.

5. WebSocket

• کجا استفاده کنیم؟
  • اپلیکیشن‌های Real-time که نیاز به ارتباط دوطرفه دارن
  • چت آنلاین، بازی‌های چندنفره، مانیتورینگ لحظه‌ای
• مثال:
  در رستوران، مدیر بتونه همزمان ببینه چند میز آزاد شد و کاربر هم نوتیفیکیشن فوری دریافت کنه.

6. SSE (Server-Sent Events)

• کجا استفاده کنیم؟
  • وقتی فقط نیاز داریم داده یک‌طرفه از سرور به کلاینت بیاد
  • استریم قیمت لحظه‌ای ارز، آب‌وهوا، وضعیت سرورها
• مثال:
  نمایش قیمت لحظه‌ای غذاها در منوی آنلاین رستوران یا نمایش نوبت‌ها در صف.

جدول مقایسه