📖 درس اول: مفاهیم پایه API؛ HTTP، REST و معماری Client-Server
🎯 هدف این درس: درک عمیق مفاهیم بنیادین API شامل پروتکل HTTP، ساختار درخواست و پاسخ، متدها، Status Codes، اصول REST و معماری Client-Server. این درس پایه و اساس تمام مباحث بعدی است.
مهمان عزیز! 👋
به اولین درس از دوره فوقپیشرفته توسعه API خوش آمدی.
شاید برایت سوال باشد که چرا یک دوره کامل را به API اختصاص دادهایم. پاسخ ساده است: امروزه هر اپلیکیشن موفقی، از گوشی موبایل تا وبسایتهای بزرگ و حتی دستگاههای هوشمند خانه، از طریق API با جهان بیرون ارتباط برقرار میکند. اگر به اطرافت نگاه کنی، هر سرویس آنلاینی که استفاده میکنی، از شبکههای اجتماعی گرفته تا اپلیکیشنهای بانکی و فروشگاههای اینترنتی، همه از API برای ارتباط با سرورهای خود استفاده میکنند.
💡 API مثل یک رستوران است!
فرض کن به رستوران میروی، به گارسون (کلاینت) میگویی چه غذایی میخواهی، گارسون سفارش را به آشپزخانه (سرور) میبرد و بعد از آماده شدن، غذا را برایت میآورد. تو نیازی نداری بدانی آشپزخانه چگونه کار میکند، فقط سفارش میدهی و نتیجه را میگیری. API دقیقاً همین نقش را در دنیای نرمافزار ایفا میکند – یک واسط استاندارد برای ارتباط بین سیستمهای مختلف.
در این درس، به جای اینکه مستقیم برویم سراغ کدنویسی، ابتدا میخواهیم درک عمیقی از این مفاهیم پیدا کنیم. چرا؟ چون در درسهای بعدی، هر خط کدی که مینویسیم، باید بدانیم دقیقاً چه کاری انجام میدهد و چرا آن را به این شکل مینویسیم. برنامهنویسی که مفاهیم پایه را خوب بلد باشد، همیشه کد بهتری مینویسد و مشکلات را سریعتر حل میکند.
🔍 API چیست و چرا به آن نیاز داریم؟
API مخفف Application Programming Interface است. به زبان ساده، API یک رابط (Interface) است که به دو نرمافزار مختلف اجازه میدهد با یکدیگر ارتباط برقرار کنند.
بیایید با یک مثال واقعیتر موضوع را روشن کنیم. فرض کن میخواهی یک اپلیکیشن هواشناسی بسازی. نیازی نیست خودت ایستگاه هواشناسی راهاندازی کنی و دادهها را جمعآوری کنی. کافی است از API یک سرویس هواشناسی مثل OpenWeatherMap استفاده کنی. با ارسال یک درخواست ساده به آن API، اطلاعات آبوهوا را دریافت میکنی و در اپلیکیشن خود نمایش میدهی.
- ✅ API به شما امکان میدهد از قابلیتهای دیگران استفاده کنید.
- ✅ API به دیگران اجازه میدهد از قابلیتهای شما استفاده کنند.
- ✅ API باعث جداسازی (Decoupling) سیستمها میشود.
- ✅ API استانداردسازی ارتباطات بین سیستمها را تضمین میکند.
🌐 پروتکل HTTP؛ زبان مشترک وب
HTTP یا HyperText Transfer Protocol، پروتکل اصلی ارتباط در وب است. وقتی یک API از طریق وب کار میکند، از HTTP برای ارسال و دریافت دادهها استفاده میکند.
ساختار یک درخواست HTTP
هر درخواست HTTP از چند بخش تشکیل شده است:
- خط درخواست (Request Line): شامل متد، مسیر (URL) و نسخه HTTP.
- سرآیندها (Headers): اطلاعات اضافی مثل نوع محتوا، احراز هویت و …
- بدنه (Body): دادههایی که ارسال میشوند (اختیاری).
HTTP Request
HTTP
1.1
# خط درخواست (Request Line)
GET /api/users/1 HTTP/1.1
# سرآیندها (Headers)
Host: example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
User-Agent: Mozilla/5.0
# بدنه (Body) - معمولاً برای درخواستهای POST یا PUT
{
"name": "یونس",
"email": "younes@example.com"
}
ساختار یک پاسخ HTTP
پاسخ HTTP نیز از سه بخش اصلی تشکیل شده است:
- خط وضعیت (Status Line): شامل نسخه HTTP، کد وضعیت و پیام آن.
- سرآیندها (Headers): اطلاعاتی مثل نوع محتوا، طول محتوا و …
- بدنه (Body): دادههای اصلی پاسخ.
HTTP Response
HTTP
1.1
# خط وضعیت (Status Line)
HTTP/1.1 200 OK
# سرآیندها (Headers)
Content-Type: application/json
Content-Length: 123
Cache-Control: no-cache
# بدنه (Body) - دادههای اصلی
{
"id": 1,
"name": "یونس",
"email": "younes@example.com",
"created_at": "2026-01-15T10:30:00Z"
}
🔄 متدهای HTTP؛ عملیاتهای اصلی
متدهای HTTP مشخص میکنند که چه نوع عملیاتی روی منبع مورد نظر انجام شود. مهمترین متدها عبارتند از:
| متد | کاربرد | مثال | بدنه |
|---|---|---|---|
| GET | دریافت داده | /api/users | ❌ |
| POST | ایجاد داده جدید | /api/users | ✅ |
| PUT | بروزرسانی کامل | /api/users/1 | ✅ |
| PATCH | بروزرسانی جزئی | /api/users/1 | ✅ |
| DELETE | حذف داده | /api/users/1 | ❌ |
💡 نکته مهم:
تفاوت PUT و PATCH در این است که PUT کل منبع را جایگزین میکند، اما PATCH فقط بخشهای مشخصی را بهروز میکند.
📊 کدهای وضعیت (Status Codes)
کدهای وضعیت به کلاینت میگویند که درخواست او چگونه پردازش شده است. این کدها به چند دسته تقسیم میشوند:
| دسته | محدوده | توضیح |
|---|---|---|
| اطلاعاتی | 1xx | دریافت اطلاعات، ادامه پردازش |
| موفقیت | 2xx | درخواست با موفقیت انجام شد |
| تغییرمسیر | 3xx | نیاز به تغییر مسیر |
| خطای کلاینت | 4xx | خطا از سمت کلاینت |
| خطای سرور | 5xx | خطا از سمت سرور |
کدهای مهم 2xx (موفقیت)
- 200 OK: درخواست با موفقیت انجام شد.
- 201 Created: منبع جدید با موفقیت ایجاد شد.
- 204 No Content: درخواست موفق بود اما محتوایی برای بازگشت وجود ندارد.
کدهای مهم 4xx (خطای کلاینت)
- 400 Bad Request: درخواست نامعتبر است.
- 401 Unauthorized: احراز هویت ناموفق.
- 403 Forbidden: دسترسی غیرمجاز.
- 404 Not Found: منبع مورد نظر پیدا نشد.
- 422 Unprocessable Entity: دادههای ارسالی نامعتبر هستند.
کدهای مهم 5xx (خطای سرور)
- 500 Internal Server Error: خطای داخلی سرور.
- 502 Bad Gateway: سرور نمیتواند پاسخ معتبری از سرور دیگر دریافت کند.
- 503 Service Unavailable: سرویس در دسترس نیست.
🔑 هدرهای HTTP حیاتی (Headers)
هدرها اطلاعات جانبی درباره درخواست یا پاسخ را حمل میکنند. مهمترین هدرها در API عبارتند از:
- Content-Type: نوع محتوای ارسالی (مثلاً
application/json). - Accept: نوع محتوایی که کلاینت میتواند دریافت کند.
- Authorization: اطلاعات احراز هویت (معمولاً توکن).
- User-Agent: اطلاعات مرورگر یا کلاینت.
- Cache-Control: کنترل کش کردن.
- CORS (Access-Control-*): مدیریت دسترسی از دامنههای دیگر.
🏛️ معماری Client-Server
در معماری کلاینت-سرور، دو بخش اصلی وجود دارد:
- کلاینت (Client): درخواستدهنده (مرورگر، اپلیکیشن موبایل، نرمافزار).
- سرور (Server): پاسخدهنده (منبع دادهها و منطق تجاری).
🔄 مزایای معماری Client-Server:
- ✅ جداسازی لایهها (Separation of Concerns).
- ✅ قابلیت توسعه مستقل هر بخش.
- ✅ امکان استفاده از چندین کلاینت با یک سرور.
- ✅ مقیاسپذیری بهتر.
🧩 اصول REST
REST مخفف Representational State Transfer است و یک معماری برای طراحی APIهای وب. یک API زمانی RESTful است که ۶ اصل زیر را رعایت کند:
- Client-Server: جداسازی کلاینت و سرور.
- Stateless: هر درخواست مستقل است و سرور وضعیت کلاینت را ذخیره نمیکند.
- Cacheable: پاسخها باید قابلیت کش شدن داشته باشند.
- Uniform Interface: رابط یکسان برای همه منابع.
- Layered System: امکان وجود لایههای میانی.
- Code on Demand (اختیاری): ارسال کد قابل اجرا به کلاینت.
💡 Stateless بودن یعنی چه؟
یعنی سرور هیچ اطلاعاتی درباره وضعیت کلاینت بین درخواستها ذخیره نمیکند. هر درخواست باید تمام اطلاعات مورد نیاز (مثل توکن احراز هویت) را همراه داشته باشد. این کار باعث میشود سرور مقیاسپذیرتر باشد.
⚖️ مقایسه REST با SOAP و GraphQL
| ویژگی | REST | SOAP | GraphQL |
|---|---|---|---|
| قالب داده | JSON, XML, HTML | XML | JSON |
| پیچیدگی | ساده | پیچیده | متوسط |
| Overfetching | وجود دارد | وجود ندارد | ندارد |
| کش کردن | ساده | متوسط | پیچیده |
| کاربرد | اکثر APIها | سیستمهای بانکی، سازمانی | اپلیکیشنهای پیچیده |
🔴 خطاهای رایج در درک مفاهیم پایه
- ❌ اشتباه: فکر کردن به API فقط به عنوان یک URL.
- ✅ درست: API یک رابط کامل با قوانین و ساختار مشخص است.
- ❌ اشتباه: استفاده از GET برای ارسال دادههای حساس.
- ✅ درست: GET فقط برای دریافت داده است و نباید بدنه داشته باشد.
- ❌ اشتباه: برگرداندن کد 500 برای خطاهای اعتبارسنجی.
- ✅ درست: برای خطاهای اعتبارسنجی باید از 400 یا 422 استفاده کرد.
- ❌ اشتباه: ذخیره وضعیت کاربر در سرور (Stateful).
- ✅ درست: API باید Stateless باشد و هر درخواست مستقل پردازش شود.
💎 نکات کلیدی درس
- ✅ API یک واسط ارتباطی بین سیستمها است.
- ✅ HTTP پروتکل اصلی ارتباط در وب است.
- ✅ متدهای اصلی: GET، POST، PUT، PATCH، DELETE.
- ✅ کدهای وضعیت به کلاینت میگویند چه اتفاقی افتاده است.
- ✅ REST یک معماری با ۶ اصل مهم است.
- ✅ API باید Stateless باشد.
- ✅ هدرها اطلاعات جانبی مهمی را حمل میکنند.
🛠️ پروژه عملی درس اول
مهمان عزیز، وقت آن رسیده که دانستههای خود را به کار بگیری!
مسئله:
فرض کن یک API ساده برای مدیریت کتابها طراحی کردهای. با توجه به مفاهیمی که یاد گرفتی، جدول زیر را کامل کن:
| عملیات | متد HTTP | مسیر (URL) | کد موفقیت |
|---|---|---|---|
| دریافت لیست کتابها | ??? | ??? | ??? |
| ایجاد کتاب جدید | ??? | ??? | ??? |
| دریافت جزئیات یک کتاب | ??? | ??? | ??? |
| بروزرسانی کامل کتاب | ??? | ??? | ??? |
| حذف کتاب | ??? | ??? | ??? |
🧪 راهحل پروژه (پاسخ)
| عملیات | متد HTTP | مسیر (URL) | کد موفقیت |
|---|---|---|---|
| دریافت لیست کتابها | GET | /api/books | 200 |
| ایجاد کتاب جدید | POST | /api/books | 201 |
| دریافت جزئیات یک کتاب | GET | /api/books/{id} | 200 |
| بروزرسانی کامل کتاب | PUT | /api/books/{id} | 200 |
| حذف کتاب | DELETE | /api/books/{id} | 204 |
📝 تمرینهای عملی
🧪 تمرین ۱ (ساده):
با استفاده از ابزارهایی مثل Postman یا Insomnia، یک درخواست GET به آدرس https://jsonplaceholder.typicode.com/posts ارسال کن و پاسخ را مشاهده کن. سپس سعی کن با استفاده از پارامترها، فقط پستهای یک کاربر خاص را دریافت کنی.
🧪 تمرین ۲ (متوسط):
یک سناریوی واقعی طراحی کن که در آن از هر ۵ متد اصلی HTTP (GET, POST, PUT, PATCH, DELETE) استفاده شده باشد. سناریو را به صورت کامل توضیح بده و مشخص کن که هر متد برای چه عملیاتی استفاده میشود.
🧪 تمرین ۳ (چالشی):
فرض کن یک API برای یک شبکه اجتماعی طراحی میکنی. برای عملیاتهای زیر، متد و مسیر مناسب را مشخص کن و کد وضعیتی که باید برگردانده شود را بنویس:
۱. دریافت پستهای یک کاربر خاص با شناسه ۵
۲. لایک کردن یک پست با شناسه ۱۲
۳. دریافت لیست کامنتهای یک پست با صفحهبندی
۴. حذف یک پست توسط ادمین
۵. بهروزرسانی تصویر پروفایل کاربر
🏁 جمعبندی درس
مهمان عزیز، در این درس یاد گرفتی:
- ✅ API چیست و چه نقشی در دنیای نرمافزار دارد.
- ✅ ساختار درخواست و پاسخ HTTP را به طور کامل درک کردی.
- ✅ با متدهای اصلی HTTP و کاربرد هرکدام آشنا شدی.
- ✅ کدهای وضعیت (Status Codes) را شناختی و معنی هرکدام را فهمیدی.
- ✅ هدرهای مهم HTTP و کاربرد آنها را یاد گرفتی.
- ✅ اصول REST را به طور کامل درک کردی.
- ✅ تفاوت REST با SOAP و GraphQL را فهمیدی.
این مفاهیم پایهای ترین و در عین حال مهمترین مباحث دنیای API هستند. در درس بعدی، این مفاهیم را به کد تبدیل میکنیم و اولین API خود را با PHP مینویسیم. آمادهای؟ 🚀
🗺️ نقشه راه دوره: شما اینجا هستید!
برای اینکه بدانی دقیقاً کجای مسیر هستی و چه درسهایی در انتظار توست، به جدول زیر نگاه کن. درس فعلی با رنگ متفاوت مشخص شده است.
| درس | عنوان درس | آنچه یاد میگیرید |
|---|---|---|
| ۱ | مفاهیم پایه API | HTTP، REST، معماری Client-Server |
| ۲ | پیادهسازی RESTful API با PHP خام | مسیریابی، متدها، پارامترها، پاسخهای JSON |
| ۳ | مدیریت دادهها و پایگاهداده | اتصال PDO، CRUD، تراکنشها، Pagination |
| ۴ | اعتبارسنجی و احراز هویت | JWT، Roles/Permissions، Middleware |
| ۵ | امنیت API پیشرفته | OWASP Top 10، SQLi، XSS، CSRF، Rate Limiting |
| ۶ | مستندسازی API با OpenAPI | Swagger، OpenAPI Specification، مستندات تعاملی |
| ۷ | Caching و افزایش عملکرد | Redis، ETag، Cache-Control، Query Optimization |
| ۸ | API Versioning و مدیریت چرخه حیات | استراتژیهای نسخهبندی، Deprecation، Backward Compatibility |
| ۹ | تست و دیباگ API حرفهای | PHPUnit، Mocking، Logging، Postman Collection |
| ۱۰ | پروژه نهایی: API فروشگاهی | پروژه کامل فروشگاه اینترنتی با تمام قابلیتها |
نظر خود را بنویسید
با ثبت نظر، به بهبود محتوای ما کمک کنید