API چیست؟ راهنمای ساده برای سازندگان اپ
API (Application Programming Interface) راهی تعریف‌شده برای این است که یک نرم‌افزار از نرم‌افزار دیگری داده بخواهد یا آن را به انجام کاری وادار کند. اپ شما درخواستی به قالبی توافق‌شده می‌فرستد — «رزروهای فردا را بده»، «این کارت را ۲۰ یورو شارژ کن»، «این متن را خلاصه کن» — و سیستم دیگر پاسخی ساخت‌یافته برمی‌گرداند. API راهی است که اجزای یک اپ با هم حرف می‌زنند و اپ شما از سرویس‌های بیرونی مثل پرداخت، ایمیل، نقشه و هوش مصنوعی استفاده می‌کند.
چرا API در ساخت با هوش مصنوعی مهم است
تقریباً هر اپ مفیدی از بخش‌هایی ساخته شده که از طریق API با هم ارتباط برقرار می‌کنند:
- درون اپ شما، صفحه‌های مرورگر، API بک‌اند خودتان را صدا می‌زنند تا داده را بارگذاری و ذخیره کنند.
- بیرون اپ شما، بک‌اند شما APIهای شرکت‌های دیگر را صدا می‌زند: Stripe برای گرفتن پرداخت، یک سرویس ایمیل برای ارسال رسید، یک ارائه‌دهنده مدل هوش مصنوعی برای تولید متن.
وقتی از یک سازنده هوش مصنوعی می‌خواهید «پرداخت بگیر» یا «خلاصه هوش مصنوعی اضافه کن»، در واقع دارد کدی می‌نویسد که یک API را صدا می‌زند. دانستن مبانی به شما کمک می‌کند بفهمید هوش مصنوعی از شما چه می‌خواهد (معمولاً یک حساب در آن سرویس و یک کلید API)، کجا ممکن است مشکل پیش بیاید و هزینه‌اش چقدر است.
یک تشبیه روزمره
به یک رستوران فکر کنید. شما وارد آشپزخانه نمی‌شوید و خودتان غذا درست نمی‌کنید. منو را می‌خوانید، آنچه می‌خواهید را به شکلی که آشپزخانه می‌فهمد به پیشخدمت می‌گویید، و او غذا را برمی‌گرداند — یا می‌گوید آن غذا تمام شده است.
- منو مستندات API است: فهرستی از آنچه می‌توانید بخواهید و اینکه چطور بخواهید.
- پیشخدمت خود API است: راه توافق‌شده‌ای که درخواست‌ها وارد و پاسخ‌ها خارج می‌شوند.
- آشپزخانه سیستم دیگر است: لازم نیست بدانید درونش چطور کار می‌کند.
- سفارش شما درخواست است؛ بشقاب پاسخ.
آشپزخانه می‌تواند اجاق‌ها و کارکنانش را عوض کند بدون اینکه روی شما اثری بگذارد، تا وقتی منو همان بماند. این ارزش واقعی API است: اجازه می‌دهد دو سیستم با هم کار کنند بدون اینکه هیچ‌کدام لازم باشد بداند دیگری چطور ساخته شده.
چطور یک درخواست API وب کار می‌کند
بیشتر APIهایی که با آن‌ها برخورد می‌کنید APIهای وب هستند که روی HTTP کار می‌کنند — همان پروتکلی که مرورگر شما استفاده می‌کند. هر درخواست چند بخش دارد:
| بخش | چیست | مثال |
|---|---|---|
| متد | نوع اقدام | GET (خواندن)، POST (ساختن) |
| URL / اندپوینت | نشانی چیزی که روی آن اقدام می‌کنید | https://api.example.com/bookings |
| هدرها | اطلاعات اضافی، از جمله اینکه شما کی هستید | Authorization: Bearer <your key> |
| بدنه | داده‌ای که می‌فرستید، برای ساختن و به‌روزرسانی | {"name": "Lena", "time": "14:00"} |
و هر پاسخ دارد:
| بخش | چیست | مثال |
|---|---|---|
| کد وضعیت | عددی که نشان می‌دهد کار چطور پیش رفت | 200 موفق، 201 ساخته شد، 404 پیدا نشد |
| بدنه | داده برگشتی، معمولاً به‌صورت JSON | {"id": 5001, "status": "confirmed"} |
JSON (JavaScript Object Notation) قالب متنی ساده‌ای از نام‌ها و مقادیر داخل آکولاد است. استاندارد تبادل داده در APIهای وب است.
REST: رایج‌ترین سبک
REST یک قرارداد پرکاربرد برای طراحی APIهای وب است. هر نوع چیز نشانی خودش را دارد و متدهای استاندارد می‌گویند با آن چه می‌کنید. این یک REST API برای یک اپ رزرو است:
| متد | اندپوینت | کارش |
|---|---|---|
GET | /api/bookings | فهرست رزروها |
GET | /api/bookings/5001 | گرفتن یک رزرو |
POST | /api/bookings | ساخت رزرو جدید |
PATCH | /api/bookings/5001 | تغییر بخشی از رزرو، مثل زمان آن |
DELETE | /api/bookings/5001 | لغو (حذف) رزرو |
PUT هم وجود دارد و به‌طور قراردادی کل رکورد را جایگزین می‌کند، در حالی که PATCH فقط فیلدهایی را که می‌فرستید تغییر می‌دهد.
کدهای وضعیتی که بیشتر می‌بینید:
| کد | معنی |
|---|---|
200 / 201 | موفق / ساخته شد |
400 | درخواست نادرست — چیزی در آنچه فرستادید اشتباه یا جا افتاده بود |
401 | احراز هویت نشده — ورود یا کلید معتبری وجود ندارد |
403 | ممنوع — شناخته شده‌اید، اما اجازه این کار را ندارید |
404 | پیدا نشد |
429 | درخواست‌های زیاد — به محدودیت نرخ رسیده‌اید |
500 | خطای سرور |
وقتی اپ شما خراب می‌شود، کد وضعیت اغلب سریع‌ترین سرنخ است. یک 401 از یک ارائه‌دهنده پرداخت معمولاً یعنی کلید API نبوده یا اشتباه بوده؛ یک 429 یعنی بیش از حد درخواست فرستاده‌اید.
REST تنها سبک نیست — GraphQL و APIهای سبک RPC هم وجود دارند — اما REST چیزی است که بیشتر سرویس‌ها و بک‌اندهای ساخته‌شده با هوش مصنوعی استفاده می‌کنند.
یک مثال کامل: تأیید رزرو
وقتی یک مشتری در یک اپ آرایشگاه وقت کوتاهی رزرو می‌کند، ممکن است چند فراخوانی API در یکی دو ثانیه رخ دهد:
۱. صفحه رزرو در مرورگر POST /api/bookings را با خدمت، زمان و جزئیات مشتری به بک‌اند شما می‌فرستد.
۲. بک‌اند شما بررسی می‌کند که نوبت آزاد است، رزرو را در پایگاه داده ذخیره می‌کند و 201 Created برمی‌گرداند.
۳. بک‌اند شما API یک سرویس ایمیل را با کلید محرمانه‌اش صدا می‌زند: «این تأییدیه را به lena@example.com بفرست.»
۴. اگر بیعانه‌ای باشد، بک‌اند شما از API درگاه پرداخت می‌خواهد یک جلسه پرداخت بسازد و مشتری را به آنجا می‌فرستد.
۵. بعداً، درگاه پرداخت به اپ شما زنگ می‌زند تا بگوید پرداخت موفق بوده. آن فراخوانی معکوس یک وب‌هوک است.
دو گام اول API خود شما بین فرانت‌اند و بک‌اند است. گام‌های ۳ تا ۵ APIهای شخص ثالث هستند.
اصطلاحات رایج
| اصطلاح | معنی |
|---|---|
| Endpoint (اندپوینت) | یک نشانی مشخص که یک API به آن پاسخ می‌دهد. |
| API key (کلید API) | رشته محرمانه‌ای که اپ شما را نزد یک سرویس شناسایی می‌کند. مثل رمز عبور با آن رفتار کنید. |
| Authentication (احراز هویت) | ثابت کردن اینکه چه کسی فراخوانی می‌کند — با کلید، توکن یا ورود. ببینید احراز هویت چیست. |
| Rate limit (محدودیت نرخ) | سقفی برای تعداد درخواست‌ها در یک بازه زمانی. |
| SDK | کتابخانه کد آماده‌ای که صدا زدن یک API مشخص را آسان‌تر می‌کند. |
| Documentation (مستندات) | همان «منو»: کدام اندپوینت‌ها وجود دارند، چه می‌پذیرند و چه برمی‌گردانند. |
| Sandbox / test mode (حالت آزمایش) | نسخه‌ای از یک سرویس برای آزمایش بدون پول واقعی یا داده واقعی. |
| Webhook (وب‌هوک) | فراخوانی از یک سرویس دیگر به اپ شما وقتی اتفاقی رخ دهد. |
اشتباهات رایج و باورهای غلط
- گذاشتن کلیدهای محرمانه در فرانت‌اند. هر چیزی در کدی که در مرورگر اجرا می‌شود می‌تواند توسط هر کسی که صفحه را باز کند دیده شود. کلیدهای محرمانه باید روی سرور و در متغیرهای محیطی یا رازها بمانند.
- چسباندن کلیدها در گفتگو. تاریخچه گفتگو ممکن است ذخیره شود. از قابلیت رازهای سازنده‌تان استفاده کنید و هر کلیدی را که لو رفته، عوض کنید.
- فرض کردن اینکه API رایگان است. بسیاری از APIها بر اساس هر درخواست یا میزان مصرف هزینه می‌گیرند — APIهای مدل هوش مصنوعی بر اساس توکن. قیمت‌ها را بررسی کنید و سقف هزینه تنظیم کنید. ببینید نحوه استفاده از APIهای LLM.
- مدیریت نکردن خطا. سرویس‌های بیرونی خاموش می‌شوند، timeout می‌دهند و به محدودیت می‌خورند. پیام‌های خطای معقول و تلاش مجدد بخواهید.
- اعتماد به مرورگر. API خودتان باید دسترسی‌ها را خودش بررسی کند. پنهان کردن یک دکمه جلوی صدا زدن مستقیم اندپوینت توسط کسی را نمی‌گیرد.
- استفاده از کلیدهای زنده هنگام آزمایش. تا آماده راه‌اندازی نیستید، از کلیدهای حالت آزمایش استفاده کنید.
چه چیزی از سازنده هوش مصنوعی‌تان بخواهید
- «این اپ از کدام APIهای بیرونی استفاده می‌کند و هزینه هرکدام چقدر است؟»
- «API پرداخت را فقط از سرور صدا بزن. کلید را از یک متغیر محیطی بخوان.»
- «همه اندپوینت‌های API ما، کاری که می‌کنند و اینکه چه کسی مجاز به صدا زدنشان است را فهرست کن.»
- «پیش از به‌روزرسانی یا حذف رزرو، روی سرور بررسی کن که کاربر واردشده مالک آن است.»
- «اگر API ایمیل خطا داد، رزرو را در هر حال ذخیره کن و خطا را ثبت کن.»
- «فعلاً از حالت آزمایش ارائه‌دهنده استفاده کن.»
APIها در Mythex
Mythex می‌تواند API اختصاصی خودتان را بسازد — به‌عنوان بخشی از یک وب‌اپ، یا به‌عنوان یک بک‌اند جداگانه با Node، Python (FastAPI)، C# یا Java که کنار فرانت‌اند اجرا می‌شود — و کدی بنویسد که سرویس‌های بیرونی را صدا می‌زند. کلیدهای آن‌ها را به‌عنوان رازهای پروژه اضافه می‌کنید نه در گفتگو، و آن‌ها در پیش‌نمایش و پس از انتشار برای اپ شما در دسترس‌اند. مستندات دستورهای آماده‌ای برای یکپارچه‌سازی هر API و ساخت بک‌اند REST API دارد.
پرسش‌ها
API به زبان ساده چیست؟
API (رابط برنامه‌نویسی کاربردی) راهی تعریف‌شده برای این است که یک نرم‌افزار از نرم‌افزار دیگر داده بخواهد یا کاری را انجام دهد. اپ شما درخواستی به قالبی توافق‌شده می‌فرستد و سیستم دیگر پاسخی برمی‌گرداند — مثل داده آب‌وهوا، نتیجه پرداخت، یا پاسخ تولیدشده توسط هوش مصنوعی.
REST API چیست؟
REST API سبک رایجی از API وب است که در آن هر نوع چیز (رزرو، مشتری) نشانی خودش را دارد و از متدهای استاندارد HTTP استفاده می‌شود: GET برای خواندن، POST برای ساختن، PUT یا PATCH برای به‌روزرسانی، و DELETE برای حذف. داده معمولاً به‌صورت JSON برمی‌گردد.
کلید API چیست و کجا باید نگهش دارم؟
کلید API رشته‌ای محرمانه است که اپ شما را نزد یک سرویس شناسایی می‌کند و اغلب اجازه می‌دهد پول خرج شود یا به داده دسترسی پیدا شود. آن را در متغیرهای محیطی یا رازهای پروژه روی سرور نگه دارید، نه در کدی که در مرورگر اجرا می‌شود و نه در یک مخزن عمومی.
تفاوت API و وب‌هوک چیست؟
با API، اپ شما وقتی بخواهد از سرویس دیگری چیزی می‌خواهد. با وب‌هوک، سرویس دیگر وقتی اتفاقی رخ دهد اپ شما را صدا می‌زند — برای مثال یک ارائه‌دهنده پرداخت که خبر می‌دهد پرداختی موفق بوده است.