vibe-coding-college-specs/chapters/07-database-and-backend/02-lesson-api-and-http-methods/spec.md

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