Што е API? Водич на едноставен јазик за градители на апликации

API (application programming interface) е дефиниран начин на кој еден софтвер бара податоци од друг или му налага да направи нешто. Вашата апликација испраќа барање во договорен формат — „дај ми ги утрешните резервации“, „наплати 20 евра на оваа картичка“, „резимирај го овој текст“ — а другиот систем враќа структуриран одговор. API-јата се начинот на кој деловите од една апликација разговараат меѓусебно, и начинот на кој вашата апликација користи надворешни услуги како плаќања, е-пошта, мапи и AI.

Зошто API-јата се важни кога градите со AI

Скоро секоја корисна апликација е составена од делови што комуницираат преку API-ја:

• Во вашата апликација, екраните во прелистувачот го повикуваат API-то на вашата сопствена позадина за да вчитаат и зачуваат податоци.
• Надвор од вашата апликација, вашата позадина ги повикува API-јата на други компании: Stripe за плаќања, давател на е-пошта за потврди, давател на AI модел за генерирање текст.

Кога од AI градител ќе побарате „прими плаќања“ или „додај AI резиме“, она што навистина го прави е пишување код што повикува API. Основното знаење ви помага да разберете што му треба на AI од вас (обично сметка кај таа услуга и API клуч), каде може да нешто тргне наопаку и колку ќе чини.

Секојдневна аналогија

Замислете ресторан. Не влегувате во кујната да готвите. Ја читате менито, му кажувате на келнерот што сакате на начин што кујната го разбира, а келнерот ви ја донесува храната — или ви вели дека јадењето е распродадено.

• Менито е документацијата на API-то: список на она што можете да го побарате и како.
• Келнерот е API-то: единствениот договорен начин на кој барањата влегуваат и одговорите излегуваат.
• Кујната е другиот систем: не треба да знаете како работи внатре.
• Вашата нарачка е барањето; чинијата е одговорот.

Кујната може да ги смени своите печки и персонал без да ве засега, сѐ додека менито останува исто. Тоа е вистинската вредност на API-то: им овозможува на два системи да работат заедно, без ниту еден да треба да знае како е изграден другиот.

Како функционира барање до веб API

Повеќето API-ја со кои ќе се сретнете се веб API-ја што работат преку HTTP, истиот протокол што го користи вашиот прелистувач. Секое барање има неколку делови:

А секој одговор има:

JSON (JavaScript Object Notation) е едноставен текстуален формат со имиња и вредности во витечки загради. Тоа е стандардниот начин на кој веб API-јата разменуваат податоци.

REST: најчестиот стил

REST е широко користена конвенција за дизајнирање веб API-ја. Секој вид работа добива своја URL адреса, а стандардните методи кажуваат што правите со неа. Ете како може да изгледа REST API за апликација за резервации:

PUT исто така постои и по конвенција го заменува целиот запис, додека PATCH ги менува само полињата што ги испраќате.

Статусните кодови што најчесто ќе ги видите:

Кога вашата апликација ќе се расипе, статусниот код често е најбрзиот траг. 401 од давател на плаќања обично значи недостасувачки или погрешен API клуч; 429 значи дека повикувате премногу често.

REST не е единствениот стил — постојат и GraphQL и API-ја во RPC стил — но REST е она што го користат повеќето услуги и позадини изградени со AI.

Работен пример: потврда за резервација

Кога клиент ќе закаже фризура во апликација за салон, за една-две секунди може да се случат неколку повици до API:

1. Страницата за резервација во прелистувачот испраќа POST /api/bookings со услугата, времето и податоците за клиентот до вашата позадина.
2. Вашата позадина проверува дали терминот е слободен, ја зачувува резервацијата во базата на податоци и враќа 201 Created.
3. Вашата позадина повикува API на давател на е-пошта со својот тајна клуч: „испрати ја оваа потврда до lena@example.com“.
4. Ако има депозит, вашата позадина го бара од API-то на давателот на плаќања да создаде сесија за плаќање и го испраќа клиентот таму.
5. Подоцна, давателот на плаќања ја повикува вашата апликација за да каже дека плаќањето е успешно. Тој обратен повик е webhook.

Првите два чекори се вашето сопствено API помеѓу frontend и backend. Чекорите 3–5 се API-ја на трети страни.

Вообичаени термини објаснети

Вообичаени грешки и погрешни верувања

• Ставање тајни клучеви во frontend. Сѐ во кодот што работи во прелистувачот може да го види секој што ќе ја посети страницата. Тајните клучеви мора да останат на серверот, во променливи на околината или тајни.
• Лепење клучеви во разговор. Историјата на разговорот може да се чува. Наместо тоа, користете ја функцијата за тајни на вашиот градител, а секој клуч што сте го изложиле — заменете го.
• Претпоставка дека API-то е бесплатно. Многу API-ја наплаќаат по барање или по единица користење — API-јата за AI модели наплаќаат по токени. Проверете ги цените и поставете ограничувања на трошењето. Видете како да користите LLM API-ја.
• Непостапување при неуспех. Надворешните услуги паѓаат, истекува времето и достигнуваат ограничувања. Побарајте разумни пораки за грешки и повторни обиди.
• Верување на прелистувачот. Вашето сопствено API мора самото да ги проверува дозволите. Скриеното копче не значи дека некој нема да може директно да го повика крајната точка.
• Користење живи клучеви при тестирање. Користете клучеви од тест режимот додека не сте подготвени за лансирање.

Што да побарате од вашиот AI градител

• „Кои надворешни API-ја ги користи апликацијата и колку чини секое од нив?“
• „Повикувај го API-то за плаќања само од серверот. Прочитај го клучот од променлива на околината.“
• „Наведи ги сите крајни точки во нашето API, што прават и кој смее да ги повикува.“
• „Провери на серверот дека најавениот корисник е сопственик на резервацијата пред да ја ажурира или избрише.“
• „Ако API-то за е-пошта не успее, сепак зачувај ја резервацијата и запиши ја грешката.“
• „Користи го тест режимот на давателот за сега.“

API-ја во Mythex

Mythex може да изгради ваше сопствено API — како дел од веб-апликација, или како посебна позадина во Node, Python (FastAPI), C# или Java што работи покрај вашиот frontend — и да го напише кодот што ги повикува надворешните услуги. Нивните клучеви ги додавате како тајни на проектот, а не во разговорот, и се достапни за вашата апликација во прегледот и откако ќе се објави. Документацијата содржи рецепти за интегрирање на било кое API и изградба на REST API позадина.

Прашања