102 lines
10 KiB
Markdown
102 lines
10 KiB
Markdown
# مشخصات درس‌نامه: مفهوم 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 و ساختار تبادل پیام با کدهای نمونه مستند گردد.
|