Какво е API? Ръководство за създатели на приложения

API (application programming interface) е определен начин една програма да пита друга за данни или да я накара да извърши нещо. Вашето приложение изпраща заявка в договорен формат — „дай ми утрешните резервации“, „таксувай тази карта за 20 евро“, „обобщи този текст“ — а другата система връща структуриран отговор. API са начинът, по който частите на приложението говорят помежду си, и начинът, по който вашето приложение използва външни услуги като плащания, имейл, карти и AI.

Защо API са важни, когато създавате с AI

Почти всяко полезно приложение се състои от части, които комуникират чрез API:

• Вътре в приложението ви екраните в браузъра извикват API на вашия собствен бекенд, за да зареждат и записват данни.
• Извън приложението ви вашият бекенд извиква API на други компании: Stripe за приемане на плащания, доставчик на имейли за изпращане на касови бележки, доставчик на AI модел за генериране на текст.

Когато поискате от AI билдър да „приема плащания“ или да „добави AI обобщение“, той всъщност пише код, който извиква API. Познаването на основите ви помага да разберете какво му е нужно от вас (обикновено акаунт при тази услуга и 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 на доставчика на плащания да създаде checkout сесия и изпраща клиента там.
5. По-късно доставчикът на плащания извиква вашето приложение, за да каже, че плащането е успешно. Това обратно извикване е webhook.

Първите две стъпки са вашият собствен API между frontend и backend. Стъпки 3–5 са API на трети страни.

Основни термини

Чести грешки и заблуди

• Поставяне на тайни ключове във frontend-а. Всичко в код, който се изпълнява в браузъра, може да бъде видяно от всеки, който посети страницата. Тайните ключове трябва да остават на сървъра, в environment variables или secrets.
• Поставяне на ключове в чата. Историята на чата може да се съхранява. Използвайте функцията за secrets на билдъра си и подменете всеки ключ, който сте разкрили.
• Предполагане, че API е безплатен. Много API таксуват на заявка или на единица използване — API на AI модели таксуват по токени. Проверявайте цените и задавайте лимити на разходите. Вижте как да използвате LLM API.
• Непредвиждане на грешки. Външните услуги спират, изтичат по време (timeout) и достигат лимити. Искайте разумни съобщения за грешка и повторни опити.
• Доверие на браузъра. Вашият собствен API трябва сам да проверява правата. Скриването на бутон не спира някого да извика endpoint-а директно.
• Използване на живи ключове при тестване. Ползвайте ключове от тестов режим, докато не сте готови да пуснете.

Какво да поискате от AI билдъра си

• „Кои външни API използва това приложение и колко струва всеки?“
• „Извиквай API за плащания само от сървъра. Чети ключа от environment variable.“
• „Изброи всеки endpoint в нашия API, какво прави и кой има право да го извиква.“
• „Провери на сървъра, че влезлият потребител е собственик на резервацията, преди да я обнови или изтрие.“
• „Ако API за имейли се провали, запази резервацията все пак и запиши грешката.“
• „Засега използвай тестовия режим на доставчика.“

API в Mythex

Mythex може да изгради собствен API — като част от уеб приложение или като отделен бекенд на Node, Python (FastAPI), C# или Java, работещ заедно с frontend-а ви — и да напише кода, който извиква външни услуги. Добавяте техните ключове като secrets на проекта, а не в чата, и те са достъпни за приложението ви в preview и след публикуване. Документацията има рецепти за интегриране на всеки API и изграждане на REST API бекенд.

Въпроси