API چیست به زبان ساده؟ آموزش کامل API برای وایب‌کدینگ

هر بار که هوای فردا رو توی گوشیتون می‌بینین، یه پرداخت آنلاین انجام می‌دین، یا از هوش مصنوعی یه سؤال می‌پرسین… پشت صحنه، دو تا برنامه دارن با هم حرف می‌زنن. زبونِ این حرف زدن، اسمش ای‌پی‌آی (API: راه وصل شدن برنامه‌ها) ـه. و هر کسی که بخواد با وایب کدینگ (Vibe Coding) یه چیز واقعی بسازه، دیر یا زود به همین ای‌پی‌آی می‌رسه. تا آخر همین ویدیو بهتون قول می‌دم: می‌فهمین ای‌پی‌آی دقیقاً چطوری کار می‌کنه، کلید ای‌پی‌آی رو درست می‌گیرین و درست نگهش می‌دارین، اشتباهی رو یاد می‌گیرین که خیلی‌ها سرش پول از دست دادن، و آخر ویدیو، با هم یه ای‌پی‌آی واقعی رو صدا می‌زنیم؛ رایگان، و بدون هیچ کلیدی. بریم که شروع کنیم!

توی قسمت قبل ترمینال (Terminal: جای تایپ دستور) رو یاد گرفتیم، و قول دادیم که بعدش بریم سراغ ای‌پی‌آی. حالا وقتشه. اگه با کلاد کد (Claude Code)، کدکس (Codex) یا آنتی‌گرویتی (Antigravity) کار می‌کنین، این ایجنت‌ها (Agent) مدام کدی می‌نویسن که به یه ای‌پی‌آی وصل می‌شه: برای پرداخت، برای ایمیل، برای نقشه، برای هوش مصنوعی. و اگه ندونین ای‌پی‌آی چیه، فقط دارین تأیید می‌زنین و امیدوارین درست کار کنه. توی این ویدیو قدم به قدم می‌ریم جلو: ای‌پی‌آی چیه، درخواست و پاسخ چطوری کار می‌کنن، endpoint و متدها چی‌ان، کلید ای‌پی‌آی چیه و چطوری مخفی نگهش داریم، کدهای وضعیت چی می‌گن، هزینه و محدودیت‌ها، صدا زدن یه مدل هوش مصنوعی، webhook، اینکه ایجنت‌ها چطوری از ای‌پی‌آی استفاده می‌کنن، اشتباه‌های رایج، و در آخر، یه نمونهٔ واقعی که همین امروز می‌تونین امتحانش کنین.

خب، ای‌پی‌آی چیه؟ ای‌پی‌آی مخفف سه تا کلمهٔ انگلیسیه، یعنی «رابط برنامه‌نویسی نرم‌افزار». ولی این اسم چیزی رو روشن نمی‌کنه؛ بیاین با یه مثال بفهمیمش. فرض کنین رفتین رستوران. سر میز می‌شینین، آشپزخونه رو نمی‌بینین، و لازم هم نیست بدونین غذا چطوری پخته می‌شه. یه منو دارین، سفارش رو به گارسون می‌دین، گارسون می‌بره آشپزخونه، و غذا رو براتون میاره. ای‌پی‌آی همون گارسونه. یه برنامه سفارش می‌ده، ای‌پی‌آی سفارش رو می‌بره به اون یکی برنامه، و جواب رو برمی‌گردونه.

منو هم همون «مستندات ای‌پی‌آی» ـه: فهرست کارهایی که می‌شه خواست، و اینکه دقیقاً چطوری باید خواست. و مهم‌ترین نکته‌ش: لازم نیست بدونین اون طرف چطوری ساخته شده. اپ آب‌وهوای گوشیتون خودش ماهواره نداره. فقط از ای‌پی‌آی یه سرویس هواشناسی می‌پرسه «هوای ونکوور الان چنده؟»، و جواب رو قشنگ نشونتون می‌ده. هر کاری که با ای‌پی‌آی می‌کنین، دو تا تیکه داره: درخواست، و پاسخ. به انگلیسی، request و response. درخواست، پیامیه که شما می‌فرستین، و چهار تا چیز توشه. آدرس، یعنی کجا می‌فرستین.

متد، یعنی چی می‌خواین: گرفتن، یا فرستادن. header ها، یعنی اطلاعات همراه، مثل کلیدتون. و گاهی یه بدنه، یعنی خودِ داده‌ای که می‌فرستین. پاسخ، چیزیه که برمی‌گرده، و دو تا تیکهٔ اصلی داره: یه کد وضعیت، که می‌گه کار درست انجام شد یا نه، و خودِ داده. مثلاً همون اپ آب‌وهوا یه درخواست می‌فرسته: آدرس سرویس هواشناسی، متدِ گرفتن، و اسم شهر. پاسخ برمی‌گرده: یه کد که می‌گه موفق بود، و دمای همین الان. و یه نکته که خیلی‌ها نمی‌دونن: همیشه شما شروع می‌کنین. ای‌پی‌آی خودش یهو بهتون پیام نمی‌ده؛ تا نپرسین، جوابی نمیاد.

این قانون یه استثنا داره، به اسم webhook، که جلوتر بهش می‌رسیم. هر ای‌پی‌آی چند تا در داره، و هر در برای یه کار. به هر کدوم از این درها می‌گن endpoint. یه endpoint در واقع یه آدرس اینترنتیه، مثل آدرس یه سایت. اولش یه آدرس پایه هست، مثلاً api.example.com، که برای کل اون ای‌پی‌آی یکیه. بعدش یه مسیر میاد که کار رو مشخص می‌کنه: /users برای کاربرها، /orders برای سفارش‌ها. و گاهی ته آدرس یه علامت سؤال میاد، با چند تا پارامتر؛ مثلاً اسم شهر، یا تعداد نتیجه‌ها.

حالا یه نکتهٔ مهم برای کار با ایجنت‌ها. endpoint ها رو فقط از مستندات رسمی بگیرین. مدل‌های هوش مصنوعی گاهی یه endpoint از خودشون می‌سازن که اصلاً وجود نداره، فقط چون شبیه چیزهای واقعیه. اگه درخواستتون مدام خطای «پیدا نشد» می‌ده، اول همین رو چک کنین. روی یه endpoint می‌شه کارهای مختلفی کرد، و متد مشخص می‌کنه دقیقاً چی می‌خواین. چهار تا اصلی داریم. GET یعنی بگیر؛ فقط خوندن، مثلاً فهرست سفارش‌ها رو بده. POST یعنی بفرست، یا بساز؛ مثلاً یه سفارش جدید ثبت کن.

PUT یا PATCH یعنی عوض کن؛ مثلاً آدرس این سفارش رو به‌روز کن. و DELETE یعنی پاک کن. یه چیز جالب: وقتی یه آدرس رو توی مرورگر می‌نویسین و Enter می‌زنین، مرورگر دقیقاً یه درخواست GET می‌فرسته. یعنی شما همین الانش هم هر روز دارین ای‌پی‌آی صدا می‌زنین، فقط اسمش رو نمی‌دونستین. و چرا مهمه؟ چون GET معمولاً بی‌خطره و چیزی رو عوض نمی‌کنه، ولی POST و DELETE واقعاً یه چیزی رو تغییر می‌دن. پس وقتی ایجنت می‌خواد یه درخواست DELETE روی داده‌های واقعی‌تون بفرسته، همون حواس‌جمعی‌ای رو داشته باشین که برای rm توی ترمینال داشتیم.

بیشتر ای‌پی‌آی ها به هر کسی جواب نمی‌دن؛ باید بدونن کی داره درخواست می‌ده. اینجاست که کلید ای‌پی‌آی میاد وسط. کلید ای‌پی‌آی یه رشتهٔ طولانی از حرف و عدده، که خود سرویس بهتون می‌ده. مثل کارت ورود یه ساختمون: هر بار که درخواست می‌دین، کارت رو نشون می‌دین، و سرویس می‌فهمه شمایین. معمولاً هم این کلید توی header درخواست فرستاده می‌شه. کلید رو معمولاً از پنل سایت همون سرویس می‌سازین، توی بخشی به اسم ای‌پی‌آی کی‌ها (API Key). و یه نکتهٔ خیلی مهم: خیلی از سرویس‌ها کلید رو فقط یه بار، همون لحظهٔ ساختن، کامل نشون می‌دن.

پس همون موقع یه جای امن ذخیره‌ش کنین. بعضی سرویس‌ها هم اجازه می‌دن برای هر کلید دسترسی محدود بذارین، مثلاً فقط خوندن. هر جا این امکان بود، برای هر پروژه یه کلید جدا بسازین، با همون دسترسی‌ای که لازم داره. اینطوری اگه یکی لو رفت، فقط همون یکی رو باطل می‌کنین. و چیزی که هیچ‌وقت نباید یادتون بره: هر درخواستی که با کلید شما فرستاده بشه، به حساب شما نوشته می‌شه. اگه سرویس پولی باشه، صورت‌حسابش هم میاد برای شما. کلید ای‌پی‌آی، کارت بانکیِ پروژه‌تونه. حالا مهم‌ترین قانون این ویدیو: کلید ای‌پی‌آی هیچ‌وقت نباید داخل خودِ کد نوشته بشه.

جای درستش فایل .env ـه، که توی قسمت ترمینال دربارش حرف زدیم. کلید اونجا به شکل یه متغیر محیطی ذخیره می‌شه، و کد فقط اسم اون متغیر رو صدا می‌زنه. و فایل .env حتماً باید توی .gitignore باشه، تا هیچ‌وقت روی گیت هاب (GitHub) نره. سه جای خطرناک دیگه هم هست. یک: کدی که توی مرورگر اجرا می‌شه، یعنی frontend. هر چیزی که توی کد صفحه باشه، هر کسی می‌تونه با ابزار توسعه‌دهندهٔ مرورگر ببینه؛ پس کلید مخفی فقط باید روی سرور بمونه. دو: اسکرین‌شات و ویدیو. سه: پیامی که برای کسی می‌فرستین، حتی برای پشتیبانی.

و اگه یه وقت کلیدتون لو رفت، پاک کردن اون commit کافی نیست، چون تاریخچهٔ Git هنوز نگهش داشته. سریع برین توی پنل سرویس، اون کلید رو باطل کنین و یه کلید تازه بسازین. ربات‌هایی هستن که مدام دنبال کلیدهای لو رفته می‌گردن؛ اینجا هر دقیقه مهمه. هر پاسخی که از ای‌پی‌آی میاد، یه عدد سه‌رقمی همراهشه، به اسم کد وضعیت. HTTP یه قسمت کامل برای خودش داره، ولی همین چند تا رو از الان بدونین، چون هر روز می‌بینینشون. دویست یعنی همه‌چی درسته. چهارصد و یک یعنی کلید نفرستادین، یا کلیدتون درست نیست.

چهارصد و سه یعنی کلید درسته، ولی اجازهٔ این کار رو ندارین. چهارصد و چهار یعنی این آدرس پیدا نشد؛ معمولاً یه endpoint اشتباه. چهارصد و بیست و نه یعنی زیادی درخواست دادین؛ یه کم صبر کنین. و پونصد یعنی مشکل از سمت خود سرویسه، نه شما. یه قانون ساده: کدهایی که با چهار شروع می‌شن، معمولاً یعنی یه چیزی توی درخواست شما ایراد داره. کدهایی که با پنج شروع می‌شن، یعنی اون طرف مشکل داره. همین یه جمله، نصف دیباگ کردن رو براتون حل می‌کنه.

وقتی ای‌پی‌آی جواب می‌ده، داده معمولاً به یه شکل استاندارد میاد، به اسم JSON. JSON یه قسمت جدا داره؛ اینجا فقط بدونین شکلش چطوریه. JSON یه سری اسم و مقداره، داخل آکولاد. مثلاً: اسم شهر، ونکوور؛ دما، دوازده. هم آدم راحت می‌خونتش، هم برنامه. و نکتهٔ کاربردیش برای ما: وقتی یه ای‌پی‌آی جوابی داد که نمی‌فهمین، کل اون JSON رو کپی کنین، بدین به ایجنت، و بپرسین «این جواب چی می‌گه، و کدوم تیکه‌ش به درد من می‌خوره؟». فقط قبلش مطمئن بشین هیچ کلید یا اطلاعات شخصی‌ای توش نیست.

ای‌پی‌آی ها بی‌نهایت نیستن. دو تا محدودیت دارن که از همون اول باید بدونین. اول، rate limit؛ یعنی سقف تعداد درخواست توی یه بازهٔ زمانی، مثلاً توی هر دقیقه. اگه ازش رد بشین، همون خطای چهارصد و بیست و نه رو می‌گیرین. راهش اینه که کد بعد از این خطا یه کم صبر کنه و دوباره امتحان کنه، و هر بار یه کم بیشتر صبر کنه: مثلاً یه ثانیه، بعد دو ثانیه، بعد چهار ثانیه. نه اینکه پشت سر هم درخواست بفرسته. دوم، هزینه. خیلی از ای‌پی‌آی ها به ازای هر درخواست، یا به ازای حجم کار، پول می‌گیرن.

ای‌پی‌آی های هوش مصنوعی معمولاً به ازای توکن (Token: واحد شمردن متن) حساب می‌کنن؛ یعنی تیکه‌های متنی که می‌فرستین و می‌گیرین. قیمت‌ها هم مدام عوض می‌شن، پس من اینجا عدد نمی‌گم؛ همیشه صفحهٔ قیمت‌گذاری خود سرویس رو ببینین. و یه کار که همین امروز بکنین: توی پنل هر سرویسی که ازش کلید دارین، اگه امکانش رو داره، یه سقف خرج یا یه هشدار هزینه بذارین. یه حلقهٔ اشتباه توی کد، می‌تونه توی یه شب هزاران درخواست بفرسته. حالا جذاب‌ترین ای‌پی‌آی ها برای ما: مدل‌های هوش مصنوعی.

اوپن‌ای‌آی (OpenAI)، Anthropic و گوگل، هر کدوم برای مدل‌هاشون ای‌پی‌آی دارن. یه نکته که خیلی‌ها رو گیج می‌کنه: اشتراک ماهانهٔ ChatGPT یا کلاد (Claude: مدل هوش مصنوعی شرکت انتروپیک)، با ای‌پی‌آی یکی نیست. اون اشتراک برای استفاده توی خودِ اپه. برای ای‌پی‌آی معمولاً باید توی پنل توسعه‌دهنده‌ها جدا حساب بسازین، جدا کلید بگیرین، و جدا پول بدین. خودِ درخواست هم ساده‌ست. یه POST به endpoint اون سرویس می‌فرستین. توی header، کلیدتون. و توی بدنه سه تا چیز اصلی: اسم مدلی که می‌خواین، پیام‌هاتون، و گاهی حداکثر طول جواب.

جواب هم یه JSON ـه که متن مدل توشه، همراه با تعداد توکن‌هایی که مصرف شده. و یه نکتهٔ طلایی: اسم دقیق مدل‌ها و شکل دقیق درخواست، هر چند وقت یه بار عوض می‌شه. پس وقتی از ایجنت می‌خواین کد هوش مصنوعی بنویسه، بهش بگین از مستندات به‌روز همون سرویس استفاده کنه، نه از حافظهٔ خودش. یادتونه گفتم همیشه شما شروع می‌کنین؟ webhook دقیقاً برعکسشه. فرض کنین یه فروشگاه آنلاین دارین، و پرداخت‌ها با یه سرویس مثل Stripe انجام می‌شه. یه راه اینه که کد شما هر چند ثانیه بپرسه: «پرداخت انجام شد؟ انجام شد؟».

این هم کُنده، هم کلی درخواست هدر می‌ده. راه بهتر webhook هست: یه آدرس روی سرور خودتون به Stripe می‌دین و می‌گین «هر وقت پرداختی انجام شد، خودت به این آدرس خبر بده». به محض پرداخت، Stripe یه درخواست POST به سرور شما می‌فرسته. یه نکتهٔ امنیتی هم داره. هر کسی می‌تونه به اون آدرس یه پیام جعلی بفرسته. برای همین سرویس‌های جدی همراه هر webhook یه امضا می‌فرستن، و کد شما باید اول اون امضا رو چک کنه، بعد سفارش رو تأیید کنه. وقتی از ایجنت webhook می‌خواین، صریحاً بگین «امضا رو هم چک کن».

خلاصه‌ش: ای‌پی‌آی یعنی شما می‌پرسین. webhook یعنی اون‌ها خبرتون می‌کنن.

و حالا، ارتباط همهٔ این‌ها با ایجنت‌ها. اول اینکه خودِ کلاد کد، کدکس و آنتی‌گرویتی هم پشت صحنه با ای‌پی‌آی به مدل‌های هوش مصنوعی وصلن. هر بار که بهشون یه چیزی می‌گین، یه درخواست به ای‌پی‌آی یه مدل فرستاده می‌شه. دوم، ایجنت موقع کار مدام از ابزار استفاده می‌کنه: فایل می‌خونه، دستور اجرا می‌کنه، توی وب می‌گرده. و خیلی از این ابزارها، پشتشون یه ای‌پی‌آی ـه. اینجاست که ام‌سی‌پی (MCP) میاد وسط. ام‌سی‌پی یه استاندارد بازه که Anthropic سال دو هزار و بیست و چهار معرفیش کرد، برای وصل کردن ایجنت‌ها به ابزارها و داده‌ها.

خیلی از سرورهای ام‌سی‌پی در واقع یه لایه روی یه ای‌پی‌آی معمولی‌ان، که ایجنت راحت‌تر بتونه ازش استفاده کنه. ام‌سی‌پی یه قسمت کامل برای خودش داره؛ اینجا فقط بدونین که بدون فهمیدن ای‌پی‌آی، ام‌سی‌پی هم مبهم می‌مونه. و یه راه عملی: وقتی از ایجنت می‌خواین یه سرویس رو وصل کنه، لینک صفحهٔ مستندات ای‌پی‌آی همون سرویس رو بهش بدین، و بگین «فقط از endpoint هایی استفاده کن که اینجا نوشته». ایجنت مستندات رو می‌خونه، endpoint درست رو پیدا می‌کنه، و خیلی کمتر چیزی از خودش می‌سازه.

حالا بیاین پنج تا اشتباه رایج رو با هم ببینیم؛ اشتباه‌هایی که تقریباً همه یه بار انجامشون می‌دن. یک: کلید داخل کد، یا داخل کد سمت مرورگر. راه درستش: .env، و سرور. دو: نخوندن پیام خطا. کد وضعیت و متن خطا معمولاً دقیقاً می‌گن چی شده. اون‌ها رو بدین به ایجنت، نه اینکه فقط بگین «کار نمی‌کنه». سه: اعتماد به endpoint یا اسم مدلی که ایجنت از حافظه نوشته. همیشه با مستندات چک کنین. چهار: درخواست توی یه حلقه، بدون سقف. حلقه‌ای که اشتباهی هزار بار یه ای‌پی‌آی پولی رو صدا بزنه، یعنی یه صورت‌حساب غیرمنتظره.

و پنج: فرض اینکه ای‌پی‌آی همیشه جواب می‌ده. سرویس‌ها گاهی کُند می‌شن، یا قطع می‌شن. کد خوب برای خطا و تأخیر هم برنامه داره: یه پیام درست به کاربر، و یه تلاش دوباره با فاصله. و حالا، قولی که اول ویدیو دادم: یه ای‌پی‌آی واقعی، رایگان، و بدون هیچ کلیدی. اسمش Open-Meteo ـه؛ یه ای‌پی‌آی آب‌وهوا، که برای استفادهٔ غیرتجاری کلید نمی‌خواد. این آدرس رو، که توی توضیحات ویدیو هم گذاشتم، توی مرورگرتون بزنین. توش عرض و طول جغرافیایی یه شهره، و اینکه دمای همین الان رو می‌خوایم.

Enter بزنین، و یه JSON می‌بینین که دمای همون لحظه توشه. همین! شما همین الان یه درخواست GET فرستادین، و پاسخ گرفتین. و اگه به جای JSON خطا دیدین، آدرس رو حرف به حرف چک کنین؛ یه حرف کم یا زیاد کافیه. حالا دیگه می‌دونین کد اون خطا داره چی بهتون می‌گه. قدم بعدی، توی ترمینال: دستور curl، و بعد همون آدرس، داخل گیومه. روی Windows، توی پاورشل (PowerShell: ترمینال جدید ویندوز) بنویسین curl.exe؛ چون اونجا curl تنها، یه دستور دیگه رو اجرا می‌کنه. و قدم آخر، با ایجنت.

به کلاد کد، کدکس یا آنتی‌گرویتی بگین: «یه صفحهٔ ساده بساز که از API Open-Meteo دمای الانِ شهر من رو بگیره و نشون بده». بعد کدی که نوشت رو باز کنین، و دنبال همین چیزهایی بگردین که امروز یاد گرفتیم: endpoint، متد، و پاسخ JSON. اون موقع می‌بینین که این کد دیگه براتون یه جعبهٔ سیاه نیست. پس بیاین مرور کنیم. ای‌پی‌آی گارسونِ بین برنامه‌هاست: شما درخواست می‌دین، و اون پاسخ میاره. هر کار یه endpoint داره، و متد می‌گه چی می‌خواین: GET برای گرفتن، POST برای فرستادن.

کلید ای‌پی‌آی کارت بانکیِ پروژه‌تونه؛ جاش توی .env ـه، نه توی کد، و اگه لو رفت، همون لحظه باطلش کنین. کدهای چهارصد یعنی ایراد از درخواست شماست، پونصد یعنی از اون طرف. rate limit و هزینه رو از اول جدی بگیرین و سقف خرج بذارین. webhook یعنی اون طرف خبرتون می‌کنه. و به ایجنت، همیشه مستندات به‌روز رو بدین. اگه این ویدیو به کارت اومد، لایک کن تا یادت نرفته. سؤالی داری؟ همین الان توی کامنت‌ها بپرس. یادت نره سابسکرایب کنی، و برای دوستات هم بفرست که اونا هم یاد بگیرن.

توی قسمت بعدی مفاهیم پایه، می‌ریم سراغ اینکه یه وب‌اپ چطوری کار می‌کنه: frontend، backend و دیتابیس، و نقش هر کدوم. می‌بینمتون.