API چیست؟ توضیح ساده با مثال واقعی برای کسانی که تازه شروع کرده‌اند

API مخفف Application Programming Interface است، یعنی راهی مشخص برای این‌که یک برنامه از برنامه‌ی دیگر کاری بخواهد. نمونه‌ی همیشگی: رستوران. شما (برنامه‌ی مشتری) به گارسون (API) سفارش می‌دهید و آشپزخانه (سرور) کار را انجام می‌دهد؛ نیازی نیست بدانید داخل آشپزخانه چه می‌گذرد.

وب API در عمل

بیشتر APIهایی که با آن‌ها سروکار دارید از طریق HTTP کار می‌کنند: برنامه یک درخواست (request) می‌فرستد و سرور یک پاسخ (response) می‌دهد. مثال از نرم‌افزاری که برای مدرسه ساختم (ClassBan): صفحه‌ی دانش‌آموزان یک درخواست می‌فرستد:

GET /api/students

و سرور فهرستی را به‌صورت JSON برمی‌گرداند:

[
  { "id": 1, "firstName": "علی", "lastName": "احمدی", "grade": "دهم - ریاضی" }
]

متدهای HTTP

هر درخواست یک «فعل» دارد که می‌گوید چه می‌خواهید:

• GET: خواندن اطلاعات.
• POST: ساختن چیز جدید.
• PUT یا PATCH: ویرایش.
• DELETE: حذف.

برای مثال در همان نرم‌افزار، POST /api/absences یک غیبت جدید ثبت می‌کند و DELETE /api/absences/5 غیبت شماره‌ی ۵ را حذف می‌کند.

کد وضعیت (Status Code)

پاسخ همیشه یک عدد دارد که نتیجه را می‌گوید:

کد	معنی
200	موفق
201	ساخته شد
400	درخواست اشتباه
401	احراز هویت نشده (باید وارد شوید)
403	دسترسی ندارید
404	پیدا نشد
500	خطای سرور

JSON چیست؟

قالب متنی ساده‌ای برای نمایش داده‌هاست: کلید و مقدار، لیست و ترکیبشان. هم برای انسان خوانا است و هم برای برنامه‌ها قابل پردازش.

احراز هویت و کلید API

بیشتر APIها می‌خواهند بدانند شما کی هستید. روش‌های رایج: کلید API (یک رشته‌ی مخصوص که همراه درخواست می‌فرستید) یا توکن که بعد از ورود می‌گیرید. نکته‌ی امنیتی مهم: کلید API را داخل کد فرانت‌اند یا مخزن عمومی نگذارید؛ هر کس صفحه را باز کند می‌بیند. کلیدها باید سمت سرور و در متغیرهای محیطی بمانند (فایل env).

نمونه‌ی آزمایش

بدون کدنویسی هم می‌توانید یک API عمومی را امتحان کنید: آدرس را در مرورگر باز کنید (برای GET)، یا از ابزارهایی مثل curl و برنامه‌های تست API استفاده کنید:

curl https://example.com/api/items

چه چیزی را همیشه چک کنیم؟

• مستندات API: آدرس‌ها، پارامترها و فرمت پاسخ.
• محدودیت تعداد درخواست (rate limit).
• کدهای خطا و پیام‌هایشان.
• نسخه‌ی API (مثلاً /v1/).

سوالات رایج

REST چیست؟ سبکی برای طراحی وب API که بر منابع (مثل students) و فعل‌های HTTP تکیه دارد.

آیا هر API باید JSON باشد؟ نه؛ قالب‌های دیگری هم هست، ولی JSON رایج‌ترین است.