مثال ساده

فرض کن یه رستوران داریم 🍔

تو وارد رستوران می‌شی، می‌خوای غذا سفارش بدی. یه منو جلوت می‌ذارن، تو از توش غذا انتخاب می‌کنی، به گارسون می‌گی چی می‌خوای، اونم میره به آشپزخونه می‌گه، غذا رو میاره برات.

حالا تو این مثال:

• تو = اپلیکیشن یا کاربر
• گارسون = REST API
• آشپزخونه = سرور یا دیتابیس
• منو = لیست خدماتی که API ارائه می‌ده (مثلاً: "لیست کاربران"، "افزودن محصول"، "حذف پیام")

---

REST API یعنی چی تو این داستان؟

REST API مثل اون گارسونه‌ست که درخواست تو رو (مثلاً می‌خوای لیست غذاها رو ببینی یا یه غذا سفارش بدی) به سرور می‌فرسته و نتیجه‌ش رو میاره.

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

---

یه مثال واقعی بزنم:

فرض کن یه سایت فروشگاه داری. می‌خوای ازش با موبایل هم استفاده کنی.

موبایل درخواست می‌ده به REST API:

GET https://example.com/products

معنیش اینه: «سلام، لطفاً لیست محصولات رو بده.»

و REST API (گارسون) می‌ره از سرور می‌پرسه و لیست رو برمی‌گردونه.

جوابش ممکنه این‌طوری باشه (فرمت JSON):

[
  { "id": 1, "name": "کفش ورزشی", "price": 200000 },
  { "id": 2, "name": "کتونی سفید", "price": 250000 }
]

---

خلاصه‌ش:

REST API یه پل ارتباطی بین دو سیستم هست که معمولاً با استفاده از اینترنت و فرمت‌های ساده مثل JSON کار می‌کنه. خیلی شبیه گارسون بین تو و آشپزخونه‌ست 😄

در ارتباط بین سیستم‌ها با استفاده از REST API، متدهای HTTP (همون روش‌های درخواست) نقش‌های متفاوتی دارند. در ادامه هرکدام رو با توضیح دقیق‌تر و مثال‌های ملموس بررسی می‌کنیم:

---

۱. GET: دریافت اطلاعات (خواندن منبع)

کارکرد:

• هدف: دریافت داده‌ها از سرور بدون ایجاد هر گونه تغییری در آن.
• ویژگی: بدون وضعیت (stateless) است، به این معنی که سرور نیازی به نگه‌داشتن اطلاعات جلسه کاربر ندارد.

مثال: تصور کن تو یک اپلیکیشن فروشگاه آنلاین هستی. وقتی لیست محصولات را می‌خواهی، یک درخواست GET به سرور ارسال می‌کنی:

GET /products

سرور به صورت JSON لیستی از محصولات را برمی‌گرداند بدون اینکه تغییری در اطلاعات صورت گیرد.

---

۲. POST: ایجاد منبع جدید

کارکرد:

• هدف: ارسال داده به سرور برای ایجاد یک منبع (مانند یک رکورد در پایگاه داده).
• ویژگی: داده‌های ارسالی در بدنه (body) درخواست به سرور ارسال می‌شود و به‌عنوان ورودی جهت ایجاد منبع جدید استفاده می‌شود.

مثال: فرض کن می‌خوای یک کتاب جدید به لیست کتاب‌ها اضافه کنی. با ارسال یک درخواست POST به سرور، اطلاعات کتاب جدید (مثلاً عنوان و نویسنده) در بدنه درخواست آمده و به لیست اضافه می‌شود:

POST /books

بدنه JSON مثال:

{
  "title": "کیمیاگر",
  "author": "پائولو کوئیلو"
}

سرور پس از اضافه کردن کتاب جدید، معمولاً اطلاعات کتاب ایجاد شده (مانند ID جدید) را به همراه کد وضعیت 201 (Created) برمی‌گرداند.

---

۳. PUT: به‌روزرسانی منبع موجود

کارکرد:

• هدف: ارسال داده به سرور جهت به‌روزرسانی یا تغییر دادن یک منبع موجود.
• ویژگی: داده‌های ارسالی جایگزین تمام یا بخشی از اطلاعات موجود می‌شود. معمولاً در درخواست PUT، کل منبع (یا نمایندگی کاملی از آن) در بدنه ارسال می‌شود.

مثال: فرض کن کتابی در لیست کتاب‌ها وجود دارد که می‌خواهی عنوان آن را تغییر دهی. با ارسال درخواست PUT به این صورت، اطلاعات جدید به‌روز می‌شود:

PUT /books/2

بدنه JSON مثال:

{
  "title": "1984 - نسخه به‌روز شده",
  "author": "جورج اورول"
}

پس از دریافت این درخواست، سرور کتاب با ID=2 را به روزرسانی می‌کند و معمولاً پاسخ موفقیت‌آمیز (مثلاً 200 OK) برگردانده می‌شود.

نکته:
گاهی PUT برای به‌روزرسانی کل منبع استفاده می‌شود. اگر بخواهیم تنها بخشی از اطلاعات را تغییر دهیم، ممکن است از متد PATCH استفاده شود.

---

✅ منظور از "کل منبع" چیه؟

وقتی می‌گیم PUT برای به‌روزرسانی کل منبع استفاده می‌شه، یعنی باید تمام اطلاعات اون منبع رو دوباره بفرستی، حتی اونایی که تغییر نکردن.

مثال:

فرض کن این منبع رو داریم:

{
  "id": 1,
  "title": "1984",
  "author": "George Orwell"
}

اگر بخوای فقط title رو با PUT تغییر بدی، باید همچنان author رو هم همراهش بفرستی، چون PUT انتظار داره کل شیء بازنویسی بشه:

{
  "title": "Animal Farm",
  "author": "George Orwell"
}

اگر author رو نفرستی، در بعضی پیاده‌سازی‌ها ممکنه حذف بشه یا مقدارش تغییر نکنه، بستگی به سرور داره.

---

✅ اما PATCH چطور؟

PATCH فقط اون قسمت‌هایی از منبع رو تغییر می‌ده که مشخص شدن. بقیه‌ی اطلاعات دست‌نخورده باقی می‌مونن.

مثال:

{
  "title": "Animal Farm"
}

این درخواست فقط title رو تغییر می‌ده و author همون‌جوری که بوده باقی می‌مونه.

---

🧠 جمع‌بندی ساده:

متد	توضیح ساده	نیاز به ارسال کل داده‌ها	مناسب برای
PUT	بازنویسی کامل	بله	وقتی کل شیء رو می‌خوای جایگزین کنی
PATCH	تغییر جزئی	نه	وقتی فقط بخشی از داده رو می‌خوای عوض کنی

---

۴. DELETE: حذف منبع موجود

کارکرد:

• هدف: ارسال درخواست به سرور جهت حذف یک منبع موجود.
• ویژگی: با دریافت درخواست DELETE، سرور منبع مورد نظر را حذف کرده و معمولاً پیام یا کد وضعیت مناسبی (معمولاً 200 OK یا 204 No Content) برگردانده می‌شود.

مثال: فرض کن می‌خواهی کتابی (مثلاً کتاب با شناسه 1) را از لیست کتاب‌ها حذف کنی:

DELETE /books/1

سرور کتاب با ID=1 را حذف کرده و تایید حذف شدن آن را به کلاینت اعلام می‌کند.

---

خلاصه

• GET: داده‌ها را از سرور می‌خواند؛ فقط برای دریافت اطلاعات است، بدون ایجاد تغییر.
• POST: داده‌ها را به سرور می‌فرستد تا یک منبع جدید ایجاد کند.
• PUT: داده‌های ارسالی را به عنوان اطلاعات جدید یک منبع موجود جایگزین می‌کند؛ یعنی بروزرسانی کامل می‌کند.
• DELETE: درخواست حذف یک منبع را به سرور می‌فرستد.

این متدها چارچوب اصلی CRUD را پیاده‌سازی می‌کنند:

• Create (ایجاد) → POST
• Read (خواندن) → GET
• Update (به‌روزرسانی) → PUT
• Delete (حذف) → DELETE