# مشخصات درس‌نامه: مفهوم API و ارتباط سرور با فرانت‌اند (APIs & HTTP Methods)
- **شناسه در سیلابس:** `L7.3`
- **فصل:** فصل ۷: داده و بک‌اند (Ch 7)
- **نوع محتوا:** 📘 درس‌نامه متنی
- **زمان تقریبی مطالعه:** ۱۲ دقیقه
- **پیش‌نیازهای مستقیم:** `L7.2` (داده و دیتابیس چیست)

---

## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
- [ ] **درک کند (Understand):** رابط برنامه‌نویسی نرم‌افزار (API) چیست و استعاره مشهور «گارسون رستوران» چگونه چرخه ارتباط میان مشتری (فرانت‌اند) و آشپزخانه (پایگاه داده) را توضیح می‌دهد.
- [ ] **درک کند (Understand):** چرخه درخواست و پاسخ (Request-Response Cycle) و ساختار داده‌های مبادلاتی در قالب زبان جهانی **JSON** چگونه کار می‌کنند.
- [ ] **تحلیل/ارزیابی کند (Evaluate):** چهار متد اساسی پروتکل HTTP و تطبیق آن‌ها با عملیات چهارگانه CRUD شامل: **GET (خواندن)، POST (ایجاد)، PUT/PATCH (ویرایش)، و DELETE (حذف)** را درک کند.
- [ ] **تحلیل/ارزیابی کند (Evaluate):** کدهای وضعیت استاندارد HTTP (کدهای ۲۰۰ موفق، ۴۰۱ عدم دسترسی، ۴۰۴ پیدا نشدن، و ۵۰۰ خطای سرور) را برای خطایابی ارتباطات نرم‌افزار تفسیر کند.
- [ ] **درک کند (Understand):** پلتفرم‌های نوین BaaS (مانند Supabase) چگونه بدون نیاز به نوشتن دستی صدها خط کد سرور، به صورت خودکار برای هر جدول یک REST API امن تولید می‌کنند.

---

## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)

### آنچه باید پوشش داده شود (In-Scope):
1. **استعاره گارسون رستوران (The Restaurant Waiter Analogy):**
   * شما (کاربر/فرانت‌اند) پشت میز نشسته‌اید و منو را می‌بینید، اما اجازه ندارید خودتان وارد آشپزخانه (دیتابیس) شوید و قابلمه‌ها را دستکاری کنید!
   * گارسون (API): سفارش شما را به آشپزخانه می‌برد، سرآشپز غذا را آماده می‌کند، و گارسون بشقاب آماده (پاسخ داده‌ها) را به میز شما بازمی‌گرداند.
2. **کالبدشکافی چرخه درخواست و پاسخ (Request & Response):**
   * **درخواست (Request):** شامل آدرس اینترنتی (Endpoint)، روش عمل (HTTP Method)، سربرگ‌ها (Headers شامل توکن ورود)، و بدنه داده‌ها (Body).
   * **پاسخ (Response):** شامل کد وضعیت (Status Code) و بسته اطلاعات نهایی در قالب استاندارد **JSON**.
3. **متدهای چهارگانه HTTP در پروژه محوری (عملیات CRUD):**
   * `GET /api/projects`: دریافت لیست تمام کارت‌های پروژه‌ها برای نمایش در ویترین عمومی (خواندن - Read).
   * `POST /api/projects`: ارسال اطلاعات یک پروژه جدید توسط ادمین برای ذخیره در دیتابیس (ایجاد - Create).
   * `PATCH /api/projects/123`: ویرایش عنوان یا عکس یک پروژه مشخص (بروزرسانی - Update).
   * `DELETE /api/projects/123`: حذف دائمی یک پروژه از پایگاه داده (حذف - Delete).
4. **الفبای کدهای وضعیت (Status Codes): چراغ راهنمایی وب:**
   * خانواده ۲۰۰ (سبز - موفقیت): `200 OK` (عملیات موفق)، `201 Created` (پروژه با موفقیت ساخته شد).
   * خانواده ۴۰۰ (زرد - خطای کلاینت): `400 Bad Request` (ورودی نامعتبر)، `401 Unauthorized` (لاگین نکرده‌اید)، `404 Not Found` (یافت نشد).
   * خانواده ۵۰۰ (قرمز - خطای سرور): `500 Internal Server Error` (کرش دیتابیس یا خطای باگ بک‌اند).
5. **فرمت جهانی JSON:** نمایش ساختار کلید-مقدار ساده در زبان تبادل داده‌ها.
6. **کال‌اوت‌های Quera:**
   * `<details class="violet">`: استعاره گارسون رستوران؛ امن‌ترین روش حفظ پایگاه داده از دسترسی مستقیم مرورگرها.
   * `<details class="red">`: کدهای وضعیت HTTP؛ نیمی از مهارت حل باگ در وایب کدینگ، نگاه کردن به کد عددی پاسخ سرور در تب Network مرورگر است.

### آنچه نباید وارد آن شویم (Out-of-Scope):
- نوشتن سرور دستی با پایتون FastAPI یا Node.js Express (سوپابیس این کار را خودکار می‌کند).
- پروتکل‌های GraphQL یا gRPC (پیچیدگی غیرضروری برای این دوره).

---

## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)

| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
| :--- | :--- | :--- |
| API (Application Programming Interface) | رابط برنامه‌نویسی کاربردی | پل و زبان مشترک ارتباطی که اجازه می‌دهد دو نرم‌افزار با یکدیگر تبادل داده کنند |
| REST API | رِست ای‌پی‌آی | معماری استاندارد و وب‌محور برای تبادل داده‌ها با استفاده از متدهای پروتکل HTTP |
| HTTP Methods / Verbs | متدهای پروتکل وب | دستورات استاندارد مشخص‌کننده نوع عملیات روی داده‌ها (GET, POST, PUT, DELETE) |
| HTTP Status Code | کد وضعیت پاسخ وب | عدد سه‌رقمی استاندارد که موفقیت یا نوع خطای پاسخ سرور را نشان می‌دهد |
| JSON | نمادگذاری اشیاء جاوااسکریپت | سبک‌ترین و پرکاربردترین فرمت متنی تبادل اطلاعات مبتنی بر جفت‌های کلید و مقدار |

---

## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:

1. **تصویر کاور درس:** `images/cover.png`
   * **موضوع:** کاور مدرن با تم تیره که دو جزیره دیجیتال فرانت‌اند و دیتابیس را متصل به یک پل نوری درخشان با نشان‌های متدهای GET, POST, DELETE نشان می‌دهد.
2. **استعاره گارسون رستوران در عملکرد API:** `images/api-restaurant-waiter-analogy.png`
   * **موضوع:** تصویر شماتیک: مشتری روی صندلی (فرانت‌اند) $\rightarrow$ گارسون مودب (API) $\rightarrow$ آشپزخانه محافظت‌شده (دیتابیس).
3. **چرخه رفت‌وبرگشت درخواست و پاسخ:** `images/request-response-cycle.png`
   * **موضوع:** اینفوگرافیک دوسطره: سطر بالا ارسال Request با متد و بادی $\rightarrow$ سطر پایین دریافت Response با کد وضعیت ۲۰۰ و دیتای JSON.
4. **ماتریس تطبیق متدها با عملیات CRUD:** `images/crud-to-http-verbs.png`
   * **موضوع:** جدول شماتیک ۴ ردیفه: ایجاد (Create = POST)، خواندن (Read = GET)، ویرایش (Update = PATCH)، حذف (Delete = DELETE).
5. **چراغ راهنمایی کدهای وضعیت HTTP:** `images/http-status-codes-traffic-light.png`
   * **موضوع:** تصویر جذاب ۳ چراغ: سبز (۲۰۰ و ۲۰۱)، زرد (۴۰۱ و ۴۰۴)، قرمز (۵۰۰) با توضیحات کوتاه کاربردی.

---

## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)

1. **تیتر اصلی:** `# مفهوم API و ارتباط سرور با فرانت‌اند: شاهراه مکالمه در وب`
2. **مقدمه:** چرا فرانت‌اند هرگز نباید به طور مستقیم به پایگاه داده وصل شود؟
3. **جدول کاور درس**
4. **استعاره گارسون رستوران: API دقیقاً چه کار می‌کند؟:** منطق امنیت و واسطه‌گری.
5. **کالبدشکافی درخواست و پاسخ (Request & Response):** اجزای یک مکالمه در اینترنت.
6. **چهار متد اصلی HTTP در دنیای واقعی:**
   * متد GET برای خواندن پروژه‌ها.
   * متد POST برای ایجاد پروژه جدید.
   * متد PATCH برای ویرایش متادیتا و سئو.
   * متد DELETE برای حذف.
7. **زبان مادری وب: فرمت داده‌های JSON:** ساختار ساده و کاربردی کلید-مقدار.
8. **باکس نکته Quera (`<details class="violet">`):** چرا Supabase نیاز به نوشتن دستی کدهای API را برای همیشه حذف کرد؟
9. **رمزگشایی از کدهای وضعیت HTTP (چراغ راهنمای خطاها):** تفاوت خطای ۴۰۱ با ۴۰۴ و ۵۰۰.
10. **باکس هشدار Quera (`<details class="red">`):** تب Network در ابزار DevTools مرورگر؛ کلید کشف مشکلات ارتباطی فرانت‌اند با سرور.
11. **جمع‌بندی درس‌نامه:** تسلط بر مفاهیم ارتباطی و ورود به درس راه‌اندازی عملی پروژه در پلتفرم ابری Supabase.

---

## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
- [ ] استعاره گارسون برای تفهیم نقش واسطه‌ای و امنیتی API به زبان ساده بیان شده باشد.
- [ ] متدهای چهارگانه HTTP و تطبیق آن‌ها با عملیات CRUD در سناریوی پروژه پورتفولیو توضیح داده شود.
- [ ] کدهای وضعیت اصلی به همراه تحلیل علت رخداد هرکدام آموزش داده شوند.
- [ ] فرمت JSON و ساختار تبادل پیام با کدهای نمونه مستند گردد.