# فصل ۰۱ — API چیست: حرف‌زدنِ برنامه با مدل

<div dir="rtl">

# فصل ۰۱ — API چیست: حرف‌زدنِ برنامه با مدل

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

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

![یک کلید روی جاکلیدی که دستی آن را نگه داشته و از بیرونِ ماشین با یک سیمِ نازک به سوکتی روی بدنهٔ یک موتورِ مدل وصل است؛ برشِ سوکت نشان می‌دهد کلید داخلِ ماشین جا نمی‌ماند](/lesson-assets/t5-s01-api-idea/prompt/01-image-key-socket.png)

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

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

## قبل از شروع

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

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

> 🧪 **آزمایشگاه:** [آزمایشگاه این فصل را باز کن](/lab/embed/hamhoosh/term-5-building/session-01-api-idea) و همان مدلی را که در این فصل درباره‌اش حرف می‌زنیم، این‌بار از پنجرهٔ `chat` امتحان کن. حواست باشد چه چیزی تایپ می‌کنی و چه چیزی می‌بینی — همین «در»ی که الان جلوی توست، در بعدی است که با کد باز می‌کنی.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

</div>

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

<div dir="rtl">

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

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

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

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

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

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

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

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

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| API | اِی‌پی‌آی | درِ استانداردی که برنامه‌ها از آن با یک سرویس حرف می‌زنند |
| API key | اِی‌پی‌آی کی | رشتهٔ محرمانه‌ای که برنامه‌ات را نزدِ سرویس شناسایی می‌کند؛ به حسابِ تو وصل است |
| BYOK | بای‌اُکِی | *Bring Your Own Key* — ابزار از هر کاربر کلیدِ خودش را می‌پرسد؛ کلید هرگز در کد نمی‌رود |

<div dir="rtl">

## تمرین‌ها

**تمرین اجباری:** «کلید بگیر، امن نگه‌دار» را انجام بده. با همان چهار قدمِ ضمیمهٔ فصل ۱ ترم ۱ (ورود، پذیرشِ شرایط، ساختِ کلید، کپی‌کردن) یک کلیدِ رایگانِ خودت بساز و آن را در یک جای امن روی دستگاهِ خودت نگه‌دار — نه داخلِ هیچ فایلِ کد. بعد در یک جمله بنویس: اگر این کلید را داخلِ یک صفحهٔ منتشرشده می‌گذاشتی، دقیقاً چه اتفاقی می‌افتاد؟

**تمرین ستاره‌دار ⭐:** یک ابزارِ آنلاینِ واقعی پیدا کن که ادعا می‌کند «رایگان با هوش مصنوعی کار می‌کند» و از تو کلیدی نمی‌خواهد. حالا مثلِ یک کارآگاه فکر کن: اگر کلیدی از تو نمی‌خواهد، هزینهٔ فراخوانی‌ها را چه کسی می‌دهد و دادهٔ تو کجا می‌رود؟ در دو جمله بنویس چرا الگوی `BYOK` از این مدل شفاف‌تر و محترمانه‌تر است.

## در فصل بعد

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

</div>

---
Source: https://yaadestan.com/courses/hamhoosh/lessons/t5/s01-api-idea (یادستان, Yaadestan)
