API چیست: حرف‌زدنِ برنامه با مدل

در این فصل چه یاد می‌گیری#

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

آخر این فصل می‌توانی:

• توضیح بدهی API چیست و چه فرقی با chat دارد
• بگویی API key چه‌کار می‌کند و چرا مالِ شخصِ خودت است
• بگویی چرا گذاشتنِ کلید داخلِ کدِ منتشرشده یعنی لو دادنِ کلید
• الگوی BYOK را توضیح بدهی: چرا ابزارِ منتشرشده از هر کاربر کلیدِ خودش را می‌پرسد

قبل از شروع#

• از فصل ۱ ترم ۱: فرقِ chatbot (پنجرهٔ گفت‌وگویی که شرکت ساخته) با model (خودِ مغزِ زیرین که جواب را تولید می‌کند).
• از فصل ۷ ترم ۱: حریم خصوصیِ داده، و اینکه ردهٔ رایگان با ردهٔ پولی از نظرِ داده فرق می‌کند.

لوازمِ این ترم: یک مرورگر و یک حسابِ رایگان که از آن کلیدِ خودت را می‌گیری. همین. روندِ گرفتنِ کلید را در فصلِ ۱ ترمِ ۱ (بخشِ ضمیمه) قدم‌به‌قدم دیدی، پس اینجا تکرارش نمی‌کنیم؛ این فصل سراغِ این می‌رود که آن کلید چیست، چه‌کار می‌کند و چرا باید مثلِ رمزِ عبور ازش محافظت کنی.

۱. دو در به یک مدل#

تا امروز همیشه از یک در با مدل حرف زده‌ای: یک صفحه یا اپ را باز کرده‌ای، در یک کادر تایپ کرده‌ای، و جواب را در یک پنجرهٔ تمیز خوانده‌ای. اسمِ این در chat است. آن پنجره را یک شرکت برای تو، یک آدم، ساخته: دکمه دارد، رنگ دارد، تاریخچهٔ گفت‌وگو را نگه می‌دارد.

ولی همان مدلِ زیرین یک درِ دوم هم دارد، درِ مخصوصِ برنامه‌ها. از این در خبری از پنجره و دکمه نیست. برنامهٔ تو یک پیامِ خام می‌فرستد و یک جوابِ خام پس می‌گیرد — بدونِ رنگ، بدونِ دکمه، فقط داده. اسمِ این درِ دوم API است. نکتهٔ کلیدی: پشتِ هر دو در یک مدلِ واحد نشسته. chat برای آدم، API برای برنامه.

چرا این مهم است؟ چون تا وقتی فقط از درِ chat وارد شوی، همیشه مهمانِ ابزارِ کسِ دیگری هستی. وقتی از درِ API وارد شوی، می‌توانی ابزارِ خودت را بسازی — یک صفحه که فقط کارِ تو را می‌کند.

۲. API دقیقاً چیست#

API یک درِ استاندارد است که برنامه‌ها از آن با یک سرویس حرف می‌زنند. مثلِ یک باجهٔ پستی فکر کن: قواعدِ روشنی دارد — پاکت را از این پنجره بده، رسید را از آن پنجره بگیر — و تا وقتی قاعده را رعایت کنی، فرقی نمی‌کند پشتِ باجه چه می‌گذرد. برنامهٔ تو لازم نیست بداند مدل چطور کار می‌کند؛ فقط باید بداند چه بفرستد و جواب کجا برمی‌گردد.

سرویسِ رایگانی که در این دوره استفاده می‌کنیم Gemini است و APIِ خودش را دارد. تو یک پیام (همان prompt) را طبقِ قاعده‌اش می‌فرستی، و مدل جوابش (همان response) را برمی‌گرداند — این‌بار نه در یک پنجرهٔ زیبا، بلکه به‌صورتِ متنِ خام که برنامه‌ات باید بخواندش. ساختارِ دقیقِ این رفت‌وبرگشت را فصلِ بعد باز می‌کنیم؛ فعلاً همین‌قدر بدان که API یعنی «قاعدهٔ حرف‌زدنِ برنامه با مدل».

قبل از ادامه، جواب بده: اگر بخواهی یک صفحهٔ وبِ خودت بسازی که از مدل جواب بگیرد، از کدام در باید وارد شوی — chat یا API؟ چرا؟

۳. API key: کارتِ شناساییِ تو#

وقتی برنامه‌ات از درِ API وارد می‌شود، سرویس باید بداند چه کسی در می‌زند. برای همین به هر کاربر یک رشتهٔ محرمانه می‌دهد به‌اسمِ API key. کلید مثلِ یک کارتِ شناسایی است: هر بار که برنامه‌ات چیزی می‌فرستد، کلید را هم همراهش می‌فرستد تا سرویس بگوید «آهان، این توست».

چرا سرویس این را لازم دارد؟ چون باید بشمارد هر کس چقدر استفاده می‌کند تا سهمیه را رعایت کند، و روی حساب‌های پولی صورت‌حساب را به همان کلید ببندد. یعنی کلیدِ تو مستقیماً به حسابِ تو وصل است.

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

⚠️ مواظب باش: ردهٔ رایگانِ Gemini ممکن است پرامپت و پاسخِ تو را برای بهترکردنِ مدل استفاده کند و استفادهٔ تجاری‌اش هم مجاز نیست. پس در این ترم دو مرز را جدی بگیر: کلید مالِ خودت است (نه در کدِ عمومی)، و دادهٔ خصوصی و حساس را اصلاً به ردهٔ رایگان نده.

۴. چرا کلید هرگز داخلِ کد نمی‌رود#

اینجا قلبِ فصل است. در این ترم ابزارت را روی یک میزبانِ static منتشر می‌کنی — جایی که فقط فایل‌های سمتِ کاربر (HTML و JavaScript) را سِرو می‌کند. یعنی هر فایلی که منتشر کنی، همه می‌توانند بازش کنند و بخوانندش. هر مرورگری یک دکمهٔ «مشاهدهٔ کد صفحه» دارد. پس اگر کلیدت را این‌طور در کد بنویسی:

// این کارِ اشتباه است — هرگز این‌طور نکن
const KEY = "AIzaSyД...کلیدِ واقعیِ من...";

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

«ولی من که یک برنامه‌نویسِ واقعی نیستم، کی کدم را نگاه می‌کند؟» — این تصورِ غلط دقیقاً همان‌جاست که کلیدها لو می‌روند. ربات‌هایی شبانه‌روز کلِ اینترنت را برای کلیدهای رهاشده می‌گردند. یک کلیدِ لو رفته معمولاً در عرضِ چند ساعت پیدا و مصرف می‌شود، نه چند ماه.

۵. الگوی BYOK: هرکس کلیدِ خودش#

پس اگر کلید نباید در کد باشد، ابزارِ منتشرشده کلید را از کجا بیاورد؟ جواب، الگویی است که ستونِ اخلاقیِ کلِ این ترم است: BYOK، یعنی Bring Your Own Key — «کلیدِ خودت را بیاور».

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

این یعنی دامنهٔ صادقانهٔ چیزی که در این ترم می‌سازی یک ابزارِ تک‌کاربرهٔ شخصی است، نه یک سرویسِ عمومی برای میلیون‌ها کاربر — که به سرورِ واقعی و مدیریتِ کلید در سمتِ سرور نیاز دارد و بیرون از حوصلهٔ این دوره است. این مرز را صریح می‌گویم تا انتظارت واقعی باشد.

💡 نکته: BYOK فقط یک ترفندِ امنیتی نیست، یک تصمیمِ محترمانه هم هست: تو دادهٔ کسی را از کیفِ خودت خرج نمی‌کنی و هزینهٔ کسی را هم به گردن نمی‌گیری. هرکس صاحبِ کلید، سهمیه و دادهٔ خودش می‌ماند.

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

واژه‌های تازهٔ این فصل#

در فصل بعد#

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