API дегеніміз не? Қолданба құрастырушыларға арналған қарапайым нұсқаулық

API (application programming interface) — бір бағдарламалық жасақтаманың екіншісінен деректер сұрауына немесе бірдеңе жасауын өтінуіне арналған анықталған тәсіл. Қолданбаңыз келісілген форматта сұрау жібереді — «ертеңгі брондауларды бер», «осы картаға 20 € салып шығарыңыз», «осы мәтінді қысқартыңыз» — ал басқа жүйе құрылымдалған жауап қайтарады. API қолданба бөліктерінің бір-бірімен сөйлесу тәсілі, сондай-ақ қолданбаңыз төлемдер, электрондық пошта, карталар және AI сияқты сыртқы қызметтерді пайдаланатын тәсіл.

Неге API AI-мен құрастырған кезде маңызды

Пайдалы қолданбалардың дерлік барлығы API арқылы сөйлесетін бөліктерден тұрады:

• Қолданбаңыздың ішінде браузердегі экрандар деректерді жүктеу және сақтау үшін өз backend-іңіздің API-ін шақырады.
• Қолданбаңыздың сыртында backend-іңіз басқа компаниялардың API-лерін шақырады: төлем алу үшін Stripe, түбіртектер жіберу үшін электрондық пошта провайдері, мәтін жасау үшін AI модель провайдері.

AI құрастырушыдан «төлем қабылда» немесе «AI қорытындысын қос» деп сұрағанда, ол нақты сол қызметтің API-ін шақыратын код жазады. Негіздерін білу AI-дан не қажет болатынын түсінуге (әдетте сол қызметтегі аккаунт және API кілті), қай жерде қате кетуі мүмкін екенін және шығын қанша болатынын білуге көмектеседі.

Күнделікті салыстыру

Мейрамхананы елестетіңіз. Сіз ас үйге кіріп, өзіңіз пісірмейсіз. Мәзірді оқисыз, аспазға түсінікті тілмен не қалайтыныңызды айтасыз, ал даяшы тағамды әкеледі — немесе тағам таусылғанын айтады.

• Мәзір — API құжаттамасы: нені сұрауға болатыны және оны қалай сұрау керектігі.
• Даяшы — API: сұраулар кіріп, жауаптар шығатын жалғыз келісілген жол.
• Ас үй — басқа жүйе: ішкі жұмысын білудің қажеті жоқ.
• Сіздің тапсырысыңыз — сұраныс; тағам — жауап.

Ас үй пештерін және қызметкерлерін ауыстыра алады, мәзір өзгермейінше сізге әсер етпейді. API-дің нақты құндылығы осында: екі жүйе бір-бірінің ішкі құрылымын білмей-ақ жұмыс істей алады.

Веб API сұрауы қалай жұмыс істейді

Сіз кездесетін API-лердің көбі браузеріңіз пайдаланатын HTTP протоколы арқылы жұмыс істейтін веб API-лер. Әр сұрауда бірнеше бөлік бар:

Әр жауапта мыналар бар:

JSON (JavaScript Object Notation) — аттар мен мәндер жиынтығының қарапайым мәтіндік форматы, фигуралы жақшаларда жазылады. Веб API деректер алмасудың стандартты тәсілі болып табылады.

REST: ең кең таралған стиль

REST — веб API жобалаудың кең таралған келісімі. Әр нәрсе түрінің өз URL-ы болады, ал стандартты әдістер сіз оған не істейтініңізді білдіреді. Брондау қолданбасының REST API-і былай болуы мүмкін:

PUT те бар және ол әдетте бүкіл жазбаны ауыстырады, ал PATCH тек жіберген өрістерді өзгертеді.

Жиі кездесетін мәртебе кодтары:

Қолданбаңыз бұзылғанда, мәртебе коды көбіне ең жылдам белгі болады. Төлем провайдерінен келген 401 әдетте жоқ немесе қате API кілтін білдіреді; 429 тым жиі шақырып жатқаныңызды білдіреді.

REST жалғыз стиль емес — GraphQL және RPC стиліндегі API-лер де бар — бірақ көбінесе қызметтер мен AI құрастырған backend-тер REST пайдаланады.

Жұмыс мысалы: брондау растауы

Клиент салон қолданбасында шаш қию брондайтын кезде, бір-екі секунд ішінде бірнеше API шақыруы болуы мүмкін:

1. Браузердегі брондау беті қызмет, уақыт және клиент мәліметтерімен POST /api/bookings сұранысын backend-іңізге жібереді.
2. Backend слоттың бос екенін тексереді, брондауды дерекқорға сақтайды және 201 Created қайтарады.
3. Backend электрондық пошта провайдерінің API-ін құпия кілтімен шақырады: «осы растауды lena@example.com-ға жібер».
4. Егер алдын ала төлем болса, backend төлем провайдерінің API-іне төлем сессиясын жасауды сұрайды және клиентті соған жібереді.
5. Кейінірек төлем провайдері төлем сәтті өткенін сіздің қолданбаңызға айту үшін қоңырау шалады. Бұл кері қоңырау — webhook.

Алғашқы екі қадам — фронтенд және backend арасындағы өз API-іңіз. 3–5-қадамдар — үшінші тарап API-лері.

Жалпы терминдер түсіндірмесі

Жиі кездесетін қателер мен қате түсініктер

• Құпия кілттерді frontend-ке салу. Браузерде іске қосылатын кодтағының бәрін кез келген келуші көре алады. Құпия кілттер серверде, орта айнымалыларында немесе құпияларда қалуы керек.
• Кілттерді чатқа қою. Чат тарихы сақталуы мүмкін. Оның орнына құрастырушыңыздың құпияларын пайдаланыңыз және ашылған кілтті ауыстырыңыз.
• API ақысыз деп ойлау. Көптеген API-лер әр сұраныс үшін немесе пайдалану бірлігі үшін ақы алады — AI модель API-лері токендермен есептеледі. Бағаны тексеріп, шығынға шек қойыңыз. Қараңыз: LLM API-лерін қалай пайдалану керек.
• Сәтсіздікті өңдемеу. Сыртқы қызметтер істен шығады, уақыт асып кетеді және шектерге тап болады. Түсінікті қате хабарларын және қайталауларды сұраңыз.
• Браузерге сену. Сіздің өз API-іңіз рұқсаттарды өзі тексеруі керек. Батырманы жасыру кімнің болса да эндпоинтті тікелей шақыруын тоқтатпайды.
• Тест кезінде тірі кілттерді пайдалану. Іске қосуға дайын болғанша тест режимі кілттерін пайдаланыңыз.

AI құрастырушыңыздан не сұрау керек

• «Бұл қолданба қай сыртқы API-лерді пайдаланады және әрқайсысы қанша тұрады?»
• «Төлем API-ін тек серверден шақырыңыз. Кілтті орта айнымалысынан оқыңыз.»
• «API-іміздегі әр эндпоинтті, оның не істейтінін және оны кімнің шақыра алатынын тізіңіз.»
• «Брондауды жаңартпас немесе жоймас бұрын, серверде кіріп тұрған пайдаланушының оның иесі екенін тексеріңіз.»
• «Электрондық пошта API-і істен шықса, брондауды бәрібір сақтаңыз және қатені журналға жазыңыз.»
• «Әзірге провайдердің тест режимін пайдаланыңыз.»

Mythex-тегі API-лер

Mythex веб қолданбаның бөлігі ретінде немесе фронтендпен бірге жұмыс істейтін бөлек backend ретінде Node, Python (FastAPI), C# немесе Java-да өз API-іңізді құра алады, сондай-ақ сыртқы қызметтерді шақыратын кодты жаза алады. Кілттерді чатқа емес, жоба құпиялары ретінде қосасыз, және олар алдын ала қарауда және жарияланғаннан кейін қолданбаңызға қолжетімді болады. Құжаттамада кез келген API-ді интеграциялау және REST API backend құру рецептері бар.

Сұрақтар