API гэж юу вэ

Танилцуулга

Өмнөх хичээлд бид интернэтийн үндсийг ойлгосон: client асууна, server хариулна, request → response.

Гэвч тэнд нэг зүйл дутуу байлаа. Бид ярихдаа browser нь хүсэлт илгээж, HTML хүлээж авдаг гэж үзсэн. Тэр HTML нь хүнд зориулагдсан — өнгө, зураг, товчлуур, текст.

Гэвч ПРОГРАММ өгөгдөл авахыг хүсвэл яах вэ?

Программд HTML хэрэггүй. Тэр нь <div class="temperature">24.3°C</div> гэсэн тэмдэглэгээнээс тоог гаргаж авахыг хүсэхгүй байна. Түүнд ЦЭВЭР ӨГӨГДӨЛ хэрэгтэй: {"temperature": 24.3}.

API бол яг тэр — программд зориулсан хаалга.

Энэ хичээлд ч бас ганц ч мөр код байхгүй. Тэр нь зориудынх. API-гийн ОЙЛГОЛТ нь түүний кодоос хамаагүй чухал. Дараагийн хичээлд (11.3) та requests санг ашиглаж, жинхэнэ өгөгдөл татна — тэр үед бүх зүйл ойлгомжтой байх болно.

Гол зүйрлэл: API бол ЦЭС

Өмнөх хичээлийн ресторан руу буцъя.

Та ширээнд суулаа. Одоо асуулт: та юу захиалж болох вэ?

Гал тогоо руу орж, тогоочид "надад ямар нэг зүйл хий" гэж хэлэх үү? Мэдээж үгүй. Тэр нь эмх замбараагүй байдал үүсгэнэ.

Оронд нь та ЦЭС авна.

Цэс нь юу хийдэг вэ?

1. Юу боломжтой болохыг ХЭЛНЭ. "Капучино, эспрессо, латте, ус, талх."

Цэсэнд байхгүй зүйлийг захиалж болохгүй. Хэрэв та "надад пиццо" гэж хэлбэл — зөөгч "тэр цэсэнд байхгүй" гэнэ. 404 Not Found (Бүлэг 11.1).

2. ЯАЖ захиалахыг хэлнэ. "Капучино: жижиг эсвэл том. Сүү: энгийн, соёо, өөх багатай."

Хэрэв та "капучино, гэхдээ ягаан өнгөтэй" гэж хэлбэл — тэр нь боломжгүй сонголт. 400 Bad Request.

3. Юу ХҮЛЭЭХИЙГ хэлнэ. Капучино захиалбал — та халуун кофе авна, шөл биш.

4. Гал тогоог НУУНА. Цэсэнд "тогооч Болд, 3-р тавиур дээрх шарсан талхыг ав" гэж бичээгүй. Та ХЭРХЭН хийгддэгийг мэдэх ШААРДЛАГАГҮЙ.

API нь яг эдгээр дөрвөн зүйлийг хийдэг.

API гэж юу вэ — тодорхойлолт

API гэдэг нь Application Programming Interface гэсэн үгсийн товчлол юм. Монголоор ойролцоогоор "программ хоорондын холбоос" гэж орчуулж болно.

Гэхдээ тэр орчуулга нь ойлголт өгөхгүй. Илүү ойлгомжтой тодорхойлолт нь:

API бол нэг программ өөр программд "би эдгээр зүйлийг хийж чадна, ингэж асуугаарай" гэж хэлдэг ТОХИРОЛЦОО юм.

Гурван түлхүүр үг:

1. ПРОГРАММ ХООРОНД. Хүн API-тай шууд ярьдаггүй. Программ ярьдаг.

2. ТОДОРХОЙ ЖАГСААЛТ. API нь ЯГ юу боломжтойг заадаг. Түүнээс гадна юу ч байхгүй.

3. ДОТООД БҮТЭЦ НУУГДСАН. Та ЯАЖ ажилладгийг мэдэх шаардлагагүй.

Бодит жишээ: цаг агаарын программ

Таны утсан дээр цаг агаарын программ байна. Та түүнийг нээхэд Улаанбаатарын өнөөдрийн температур харагдана.

Асуулт: тэр тоо хаанаас ирсэн бэ?

Таны утас температур ХЭМЖДЭГГҮЙ. Түүнд термометр байхгүй.

Хариулт: тэр программ нь ЦАГ АГААРЫН API -аас асуусан.

Юу болов?

1. Та программыг нээв

2. Программ (client) нь цаг агаарын сервер рүү хүсэлт илгээв: GET /forecast?latitude=47.92&longitude=106.92

3. Сервер нь өөрийн өгөгдлийн сангаас (эсвэл хиймэл дагуулаас, эсвэл цаг уурын станцуудаас) мэдээллийг олов

4. Сервер нь JSON буцаав: {"temperature": 24.3, "wind_speed": 12.5}

5. Программ нь тэр JSON -ыг уншиж, дэлгэц дээр гоё харуулав

Таны утасны программ нь цаг агаарыг ХЭРХЭН хэмждэгийг МЭДЭХГҮЙ. Тэр зөвхөн асууж, хариу авдаг.

Тэр бол API-ийн БҮХ МӨН ЧАНАР.

API-ууд хаа сайгүй байдаг

Одоо энэ санааг өргөжүүлье. Та өдөр бүр хэдэн зуун API ашигладаг — мэдэхгүйгээр.

Google Maps. Хоол хүргэлтийн программ нь газрын зураг харуулдаг. Тэр компани өөрөө газрын зураг хийгээгүй — тэд Google-ийн API-аас авдаг.

Төлбөрийн систем. Онлайн дэлгүүр нь карт төлбөр авдаг. Тэд банктай шууд холбогддоггүй — тэд төлбөрийн API ашигладаг.

Нэвтрэлт. "Google-ээр нэвтрэх" товчлуур. Тэр сайт нь таны Google нууц үгийг МЭДЭХГҮЙ. Тэр зөвхөн Google-ийн API-аас "энэ хүн үнэхээр Болд мөн үү?" гэж асуудаг.

Валютын ханш, хувьцааны үнэ, нислэгийн хуваарь, орчуулга, зураг таних, ЧАТБОТ — бүгд API.

Орчин үеийн программ бол ихэвчлэн API-уудын ХОСЛОЛ юм. Та бүх зүйлийг өөрөө бүтээх шаардлагагүй — та бусдын хийсэн зүйлийг ашиглана.

Бүлэг 15-д та ӨӨРИЙН API бичнэ. Тэгвэл бусад программ таны өгөгдлийг ашиглаж чадна.

API-гийн үндсэн бүтэц

Одоо API яаж зохион байгуулагддагийг харъя.

API нь хэдэн ENDPOINT -ээс бүрдэнэ.

Endpoint гэдэг нь "хаяг + method" гэсэн хослол юм — өөрөөр хэлбэл ТОДОРХОЙ нэг үйлдэл.

Номын сангийн API-г төсөөлье:

Мөр бүр нь нэг ENDPOINT.

Танил харагдаж байна уу?

Бүлэг 10.4-ийн ZAMUUD dictionary-г санаж байна уу?

python

ZAMUUD: dict[tuple[str, str], Callable] = {}

ZAMUUD[("GET", "/nomnuud")] = nomnuud_jagsaakh
ZAMUUD[("POST", "/nomnuud")] = nom_nemekh

Тэр бол ЯГ ЭНЭ ХҮСНЭГТ. Key нь (method, зам) гэсэн tuple — яг л endpoint.

Тэгэхээр API бол endpoint-уудын жагсаалт бөгөөд тэдгээр нь функцүүдтэй холбогдсон байдаг.

Бүлэг 15-д та яг ийм хүснэгт барина:

python

@app.get("/nomnuud")
def nomnuud_jagsaakh(): ...

@app.post("/nomnuud")
def nom_nemekh(): ...

Тэр л болоо. API бол илбэ биш — тэр бол бүртгэгдсэн функцүүдийн жагсаалт.

REST — API бүтээх заншил

Дээрх хүснэгтэд нэг ЗҮЙ ТОГТОЛ байгааг анзаарсан уу?

• Ижил зам (/nomnuud), өөр method → өөр үйлдэл

• GET нь УНШИНА, POST нь ҮҮСГЭНЭ, DELETE нь УСТГАНА

• Тодорхой зүйлд хандахдаа ID -г замд оруулна (/nomnuud/123)

Энэ зүй тогтлыг REST гэж нэрлэдэг.

REST бол ЗААВАЛ дагах хууль БИШ. Тэр нь ЗАНШИЛ — олон программист дагадаг сайн зуршил юм.

Яагаад заншил хэрэгтэй вэ?

Учир нь тэр нь API-г ТААМАГЛАХ БОЛОМЖТОЙ болгодог.

Хэрэв та шинэ API-тай тааралдвал, түүний documentation-ыг бүрэн уншихаас өмнө та ТААМАГЛАЖ чадна:

• GET /gishuud — гишүүдийг жагсаана

• GET /gishuud/1001 — 1001 дугаартай гишүүнийг өгнө

• POST /gishuud — шинэ гишүүн нэмнэ

Ихэнх тохиолдолд таны таамаг ЗӨВ байх болно. Тэр нь REST-ийн бүх зорилго.

REST-ийн үндсэн дүрмүүд:

1. Нэр үг ашигла, үйл үг биш. /nomnuud (зөв), /nom_avakh (буруу). Үйлдлийг METHOD хэлнэ.

2. Олон тоо ашигла. /nomnuud, /gishuud.

3. Method нь үйлдлийг тодорхойлно. GET, POST, PUT, DELETE.

4. ID -г замд оруул. /nomnuud/123.

5. Шүүлт, эрэмбэлэлтийг query parameter -д оруул. /nomnuud?angilal=түүх&erembe=on.

Энэ курс нь REST-ийг гүнзгий үзэхгүй. Гэхдээ Бүлэг 15-д та REST заншлын дагуу API бичих болно.

Query parameter — нарийвчлал

Бүлэг 11.1-т бид query parameter -ыг товч харсан:

?latitude=47.92&longitude=106.92

Одоо тэдгээрийг зохих ёсоор нь ойлгоцгооё.

Query parameter нь функцийн KEYWORD ARGUMENT -тай ЯГ ИЖИЛ санаа (Бүлэг 3.2).

Харьцуулъя:

python

# Python функц
tsag_agaar_avakh(latitude=47.92, longitude=106.92, days=7)

# API endpoint
GET /forecast?latitude=47.92&longitude=106.92&days=7

Бүтэц нь ижилхэн: key=value, олон байвал & -ээр холбоно.

Мөн default утга ч ажилладаг (Бүлэг 3.1):

GET /forecast?latitude=47.92&longitude=106.92

days -ыг өгөөгүй. Сервер нь default утга ашиглана (магадгүй 3 хоног).

Query parameter хэзээ ашиглах вэ:

• Шүүх: /nomnuud?angilal=түүх

• Эрэмбэлэх: /nomnuud?erembe=on&chiglel=buurah

• Хуудаслах: /nomnuud?khuudas=2&hemjee=20

• Хайх: /nomnuud?khaikh=Монгол

• Тохиргоо: /forecast?units=celsius

Path parameter -тай харьцуулъя:

• /nomnuud/123 — path parameter. "ЭНЭ ТОДОРХОЙ ном." Заавал байх ёстой.

• /nomnuud?angilal=түүх — query parameter. "Номнууд, ГЭХДЭЭ шүүлттэй." Сонголттой.

Санах арга: path нь "аль зүйл", query нь "ямар нөхцөлтэй."

API-гийн DOCUMENTATION — ЦЭС

Одоо хамгийн чухал практик зүйл рүү орно.

Ямар ч API-г ашиглахын өмнө та түүний DOCUMENTATION -ыг унших ёстой.

Documentation бол ЦЭС юм. Тэр нь:

• Ямар endpoint байгааг жагсаана

• Endpoint бүрд ямар параметр хэрэгтэйг хэлнэ

• Ямар хариу ирэхийг харуулна

• Жишээ өгнө

Documentation-гүй API нь ЦЭСГҮЙ ресторан юм. Та юу захиалахаа мэдэхгүй.

Ердийн API documentation нь ойролцоогоор ийм харагддаг:

GET /forecast

Тайлбар: Тодорхой байршлын цаг агаарын мэдээ.

Параметрүүд:
  latitude   (заавал, тоо)  — өргөрөг
  longitude  (заавал, тоо)  — уртраг
  current    (сонголттой, текст) — одоогийн үзүүлэлтүүд
  daily      (сонголттой, текст) — өдөр тутмын үзүүлэлтүүд

Хариу (200 OK):
{
  "latitude": 47.92,
  "longitude": 106.92,
  "current": {
    "temperature_2m": 24.3,
    "wind_speed_10m": 12.5
  }
}

Алдаа:
  400 — параметр буруу
  429 — хэт олон хүсэлт

Танил бүтэц: параметрүүд (заавал/сонголттой — Бүлэг 3.1!), төрлүүд (тоо/текст — Бүлэг 4!), JSON хариу (Бүлэг 6!).

Та энэ documentation-ыг УНШИЖ ЧАДНА. Бүх ойлголт таны гарт байна.

Documentation унших нь өөрөө ур чадвар бөгөөд бид түүнийг Бүлэг 15.3-т тусад нь үзнэ.

Бүлэг 15-ийн урьдчилсан амт: АВТОМАТ documentation

Одоо би нэг зүйлийг хэлье, тэр нь Бүлэг 15-ийн хамгийн том шагнал байх болно.

Дээрх documentation-ыг хэн бичсэн бэ? ХҮН. Гараар.

Тэр нь асуудалтай. Учир нь код өөрчлөгдөхөд — documentation нь ХУУЧИРНА. Хэн нэгэн шинэ параметр нэмнэ, гэхдээ documentation-д бичихээ мартна. Дараа нь бусад программист буруу мэдээллийг уншиж, төөрөгдөнө.

FastAPI нь энэ асуудлыг БҮРМӨСӨН шийддэг.

Та зөвхөн код бичнэ:

python

@app.get("/nomnuud")
def nomnuud_jagsaakh(angilal: str | None = None) -> list[Nom]:
    ...

Дараа нь /docs хаягийг нээхэд — БҮРЭН, ИНТЕРАКТИВ documentation харагдана. Тэнд:

• Бүх endpoint жагсаагдсан

• Параметр бүр, түүний ТӨРӨЛ, заавал эсэх

• Ямар хариу ирэхийг харуулсан

• Товчлуур дарж, ТЭР ДОР НЬ туршиж болно

Тэр бүхэн ХААНААС гарч ирсэн бэ?

ТАНЫ TYPE HINT -ЭЭС.

angilal: str | None = None гэсэн нэг мөрөөс FastAPI нь мэдсэн:

• Параметрийн нэр: angilal

• Төрөл: string

• Заавал биш (default нь None)

-> list[Nom] гэснээс мэдсэн:

• Хариу нь Nom объектуудын жагсаалт

• Nom -ын бүх талбар (Pydantic class-аас)

Documentation нь ХЭЗЭЭ Ч хуучрахгүй, учир нь тэр нь кодоос АВТОМАТААР үүсдэг.

Бүлэг 4.1-т би ингэж хэлсэн:

"Type hint нь ГУРВАН хүлээн авагчид зориулагдсан: хүн, editor, хэрэгслүүд. Мөн дөрөв дэх нь: зарим framework нь hint-ийг УНШИЖ, ажиллуулдаг."

Тэр дөрөв дэх нь ЭНЭ.

Ямар API-ууд байдаг вэ

Практик мэдээлэл: API-ууд хэдэн төрөлтэй.

1. Нээлттэй, түлхүүргүй (public, no key)

Хэн ч ашиглаж болно. Бүртгүүлэх шаардлагагүй.

Жишээ: Open-Meteo (цаг агаар), REST Countries (улс орны мэдээлэл).

Бид Хичээл 11.3-т яг ийм API ашиглана — учир нь тэр нь бүртгэл шаардахгүй, шууд ажиллана.

2. Нээлттэй, түлхүүртэй (public, API key)

Бүртгүүлж, API key (түлхүүр) авах хэрэгтэй. Тэр нь урт, санамсаргүй текст:

a8f5f167f44f4964e6c998dee827110c

Хүсэлт бүрд түүнийг ХАМТ илгээнэ. Сервер нь "аан, энэ бол Болд" гэж мэднэ.

Яагаад түлхүүр хэрэгтэй вэ?

• Хязгаарлах: үнэгүй хэрэглэгч өдөрт 1000 хүсэлт. Түлхүүргүй бол хэн хэдийг илгээснийг мэдэх боломжгүй.

• Мөнгө авах: илүү их хүсэлт хэрэгтэй бол — төлбөр төл.

• Хамгаалах: хэрэв хэн нэгэн API-г буруугаар ашиглавал — түлхүүрийг нь хаах.

АНХААРУУЛГА: API key -ыг ХЭЗЭЭ Ч кодод шууд бичиж болохгүй!

python

API_KEY = "a8f5f167f44f4964e6c998dee827110c"     # БУРУУ!

Хэрэв та кодоо GitHub -д байршуулбал — таны түлхүүр НИЙТЭД харагдана. Хэн ч түүнийг ашиглаж, таны нэрийн өмнөөс хүсэлт илгээж, таныг төлбөрт унагаж болно.

Зөв арга: орчны хувьсагч (environment variable) эсвэл тусдаа файл.

Энэ курс нь API key шаарддаг API ашиглахгүй, тиймээс бид энэ сэдвийг гүнзгий үзэхгүй. Гэхдээ дүрмийг санаж яваарай.

3. Хаалттай, дотоод (private)

Зөвхөн тухайн компанийн дотоод программууд ашиглана. Гаднаас хандах боломжгүй.

Туршаад үзээрэй

Хэрэв сонирхвол: browser нээгээд, дараах хаягийг хаягийн мөрөнд бичээд Enter дараарай:

https://api.open-meteo.com/v1/forecast?latitude=47.92&longitude=106.92&current=temperature_2m

Та JSON -ыг ӨӨРИЙН НҮДЭЭР харна.

json

{"latitude":47.92,"longitude":106.92,"generationtime_ms":0.02,"utc_offset_seconds":0,"timezone":"GMT","timezone_abbreviation":"GMT","elevation":1301.0,"current_units":{"time":"iso8601","interval":"seconds","temperature_2m":"°C"},"current":{"time":"2026-07-13T14:00","interval":900,"temperature_2m":24.3}}

Энэ бол Улаанбаатарын ОДООГИЙН температур. Жинхэнэ өгөгдөл, жинхэнэ сервер.

Chrome нь JSON -ыг автоматаар форматлаж, гоё харуулж болно (эсвэл "JSON Viewer" өргөтгөл суулгаж болно).

Одоо параметрүүдийг өөрчилж үзээрэй:

• latitude=48.0&longitude=100.0 — өөр байршил

• current=temperature_2m,wind_speed_10m — хоёр үзүүлэлт

• daily=temperature_2m_max + &timezone=Asia/Ulaanbaatar — өдөр тутмын

Та browser -ээр API-тай ярьж байна. Тэр нь GET хүсэлт илгээж, JSON хүлээж авч байна.

Дараагийн хичээлд та ЯГ ТЭР зүйлийг PYTHON-оор хийнэ.

Мөн хүсвэл: зориудаар буруу параметр бичээд юу болохыг хараарай:

https://api.open-meteo.com/v1/forecast?latitude=тэнэг

Та 400 Bad Request ба тодорхой алдааны мессежийг харах болно.

Түгээмэл эндүүрлүүд

1. API бол "интернэт" гэж бодох

API бол интернэт БИШ. Тэр нь ТОДОРХОЙ програмын ТОДОРХОЙ хаалга юм. Интернэт бол зам, API бол ресторан.

2. API бол зөвхөн вэб гэж бодох

Үнэндээ API гэдэг нь илүү ерөнхий ойлголт. Python-ы json модуль ч бас API-тай (json.dump, json.load). Тэр нь "ингэж ашигла" гэсэн тохиролцоо.

Гэхдээ практикт "API" гэж хэлэхэд ихэнхдээ вэб API -г хэлдэг. Энэ курсэд ч мөн адил.

3. API бол өгөгдөл гэж бодох

API бол өгөгдөл БИШ — тэр нь өгөгдөл АВАХ ЗАМ. Цэс бол хоол биш.

4. Documentation унших шаардлагагүй гэж бодох

Хамгийн түгээмэл, хамгийн үнэтэй алдаа. Documentation-гүйгээр API ашиглах нь цэсгүйгээр захиалга өгөхтэй адил. Та таамаглаж, алдаж, цаг үрнэ.

Товч дүгнэлт

• API бол программд зориулсан хаалга. Browser нь HTML авдаг (хүнд), API нь JSON буцаадаг (программд).

• API бол ЦЭС: юу боломжтойг хэлнэ, яаж захиалахыг хэлнэ, юу хүлээхийг хэлнэ, дотоод бүтцийг НУУНА.

• Тодорхойлолт: API бол нэг программ өөр программд "би эдгээр зүйлийг хийж чадна, ингэж асуугаарай" гэж хэлдэг ТОХИРОЛЦОО.

• Та өдөр бүр хэдэн зуун API ашигладаг: газрын зураг, төлбөр, нэвтрэлт, цаг агаар, орчуулга.

• ENDPOINT = method + зам. Жишээ: GET /nomnuud, POST /nomnuud.

• API бол ENDPOINT-уудын жагсаалт, тэдгээр нь функцүүдтэй холбогдсон. Бүлэг 10.4-ийн ZAMUUD dictionary нь ЯГ ЭНЭ.

• REST нь ЗААВАЛ БИШ, гэхдээ түгээмэл ЗАНШИЛ: нэр үг ашигла (/nomnuud), method нь үйлдлийг хэлнэ, ID -г замд оруул (/nomnuud/123), шүүлтийг query -д оруул.

• Query parameter (?key=value&key=value) нь функцийн KEYWORD ARGUMENT -тай ЯГ ИЖИЛ (Бүлэг 3.2). Default утга ч ажиллана.

• Path parameter (/nomnuud/123) = "аль зүйл", query parameter (?angilal=түүх) = "ямар нөхцөлтэй."

• DOCUMENTATION бол ЦЭС. Түүнийг унших нь ЗААВАЛ. Documentation-гүй API нь цэсгүй ресторан.

• FastAPI нь documentation-ыг ТАНЫ TYPE HINT -ЭЭС АВТОМАТААР үүсгэдэг → хэзээ ч хуучрахгүй. Бүлэг 15-ын хамгийн том шагнал.

• API-гийн төрлүүд: түлхүүргүй (бид эдгээрийг ашиглана), түлхүүртэй (API key-ыг кодод ХЭЗЭЭ Ч бүү бич!), дотоод.

Дараагийн хичээлд ЭЦЭСТ НЬ КОД БИЧНЭ.

Бид requests санг суулгана — тэр үед Бүлэг 1-ийн venv ба pip зуршил ажилд орно. Дараа нь requests.get(url) гэж бичээд, жинхэнэ API-аас жинхэнэ өгөгдөл татна.

Тэр мөч — таны программ анх удаа интернэтээс мэдээлэл авах мөч — бол энэ курсийн хамгийн сэтгэл догдлом мөчүүдийн нэг юм. Бид түүнийг зохих ёсоор нь тэмдэглэнэ.