https://github.com/notesparvvaresh/rest-api
توضیح با مثال از کارکرد rest api و پروژه با flask
https://github.com/notesparvvaresh/rest-api
flask rest-api
Last synced: 5 months ago
JSON representation
توضیح با مثال از کارکرد rest api و پروژه با flask
- Host: GitHub
- URL: https://github.com/notesparvvaresh/rest-api
- Owner: notesparvvaresh
- License: mit
- Created: 2025-04-08T07:38:02.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-08T12:16:17.000Z (about 1 year ago)
- Last Synced: 2025-05-08T00:31:54.912Z (about 1 year ago)
- Topics: flask, rest-api
- Language: Python
- Homepage:
- Size: 5.86 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# مثال ساده
### فرض کن یه رستوران داریم 🍔
تو وارد رستوران میشی، میخوای غذا سفارش بدی. یه **منو** جلوت میذارن، تو از توش غذا انتخاب میکنی، به **گارسون** میگی چی میخوای، اونم میره به **آشپزخونه** میگه، غذا رو میاره برات.
حالا تو این مثال:
- **تو** = اپلیکیشن یا کاربر
- **گارسون** = REST API
- **آشپزخونه** = سرور یا دیتابیس
- **منو** = لیست خدماتی که API ارائه میده (مثلاً: "لیست کاربران"، "افزودن محصول"، "حذف پیام")
---
### REST API یعنی چی تو این داستان؟
REST API مثل اون گارسونهست که درخواست تو رو (مثلاً میخوای لیست غذاها رو ببینی یا یه غذا سفارش بدی) به سرور میفرسته و نتیجهش رو میاره.
تو هیچ وقت مستقیم با آشپزخونه (سرور) حرف نمیزنی، بلکه از طریق گارسون (API) باهاش در ارتباطی.
---
### یه مثال واقعی بزنم:
فرض کن یه سایت فروشگاه داری. میخوای ازش با موبایل هم استفاده کنی.
موبایل درخواست میده به REST API:
```
GET https://example.com/products
```
معنیش اینه: «سلام، لطفاً لیست محصولات رو بده.»
و REST API (گارسون) میره از سرور میپرسه و لیست رو برمیگردونه.
جوابش ممکنه اینطوری باشه (فرمت JSON):
```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 مثال:
```json
{
"title": "کیمیاگر",
"author": "پائولو کوئیلو"
}
```
سرور پس از اضافه کردن کتاب جدید، معمولاً اطلاعات کتاب ایجاد شده (مانند ID جدید) را به همراه کد وضعیت 201 (Created) برمیگرداند.
---
## ۳. PUT: بهروزرسانی منبع موجود
**کارکرد:**
- **هدف:** ارسال داده به سرور جهت بهروزرسانی یا تغییر دادن یک منبع موجود.
- **ویژگی:** دادههای ارسالی جایگزین تمام یا بخشی از اطلاعات موجود میشود. معمولاً در درخواست PUT، کل منبع (یا نمایندگی کاملی از آن) در بدنه ارسال میشود.
**مثال:**
فرض کن کتابی در لیست کتابها وجود دارد که میخواهی عنوان آن را تغییر دهی. با ارسال درخواست PUT به این صورت، اطلاعات جدید بهروز میشود:
```
PUT /books/2
```
بدنه JSON مثال:
```json
{
"title": "1984 - نسخه بهروز شده",
"author": "جورج اورول"
}
```
پس از دریافت این درخواست، سرور کتاب با ID=2 را به روزرسانی میکند و معمولاً پاسخ موفقیتآمیز (مثلاً 200 OK) برگردانده میشود.
**نکته:**
گاهی PUT برای بهروزرسانی کل منبع استفاده میشود. اگر بخواهیم تنها بخشی از اطلاعات را تغییر دهیم، ممکن است از متد PATCH استفاده شود.
---
### ✅ منظور از "کل منبع" چیه؟
وقتی میگیم `PUT` برای بهروزرسانی *کل منبع* استفاده میشه، یعنی باید **تمام اطلاعات اون منبع** رو دوباره بفرستی، حتی اونایی که تغییر نکردن.
#### مثال:
فرض کن این منبع رو داریم:
```json
{
"id": 1,
"title": "1984",
"author": "George Orwell"
}
```
اگر بخوای فقط `title` رو با `PUT` تغییر بدی، باید همچنان `author` رو هم همراهش بفرستی، چون `PUT` انتظار داره کل شیء بازنویسی بشه:
```json
{
"title": "Animal Farm",
"author": "George Orwell"
}
```
اگر `author` رو نفرستی، در بعضی پیادهسازیها ممکنه حذف بشه یا مقدارش تغییر نکنه، بستگی به سرور داره.
---
### ✅ اما `PATCH` چطور؟
`PATCH` فقط اون قسمتهایی از منبع رو تغییر میده که مشخص شدن. بقیهی اطلاعات دستنخورده باقی میمونن.
#### مثال:
```json
{
"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 را پیادهسازی میکنند:
- **C**reate (ایجاد) → POST
- **R**ead (خواندن) → GET
- **U**pdate (بهروزرسانی) → PUT
- **D**elete (حذف) → DELETE