Что такое API? Простой гид для создателей приложений

API (интерфейс прикладного программирования) — это заранее определённый способ, которым одна программа запрашивает у другой данные или просит её что-то сделать. Ваше приложение отправляет запрос в согласованном формате — «дай бронирования на завтра», «спиши 20 евро с этой карты», «суммируй этот текст» — а другая система присылает структурированный ответ. API — это то, как части приложения общаются между собой, и то, как ваше приложение пользуется внешними сервисами: платежами, email, картами и ИИ.

Почему API важны, когда вы создаёте приложение с помощью AI

Почти каждое полезное приложение состоит из частей, которые общаются через API:

• Внутри приложения экраны в браузере вызывают API вашего собственного бэкенда, чтобы загружать и сохранять данные.
• Вне приложения ваш бэкенд вызывает API других компаний: Stripe для приёма платежей, почтовый сервис для отправки чеков, провайдер моделей ИИ для генерации текста.

Когда вы просите 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 платёжного провайдера создаёт сессию оплаты и отправляет клиента туда.
5. Позже платёжный провайдер вызывает ваше приложение, чтобы сообщить, что оплата прошла. Этот обратный вызов и есть webhook.

Первые два шага — ваш собственный API между фронтендом и бэкендом. Шаги 3–5 — API сторонних сервисов.

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

Частые ошибки и заблуждения

• Секретные ключи во фронтенде. Всё, что находится в коде, который выполняется в браузере, может увидеть любой, кто зайдёт на сайт. Секретные ключи должны оставаться на сервере, в переменных окружения или секретах.
• Вставка ключей в чат. История чата может сохраняться. Используйте функцию секретов вашего конструктора, а любой раскрытый ключ перевыпустите.
• Уверенность, что API бесплатен. Многие API берут плату за каждый запрос или за единицу использования — API моделей ИИ считают по токенам. Проверяйте цены и ставьте лимиты расходов. См. как пользоваться API LLM.
• Игнорирование сбоев. Внешние сервисы падают, не отвечают вовремя и упираются в лимиты. Попросите понятные сообщения об ошибках и повторные попытки.
• Доверие браузеру. Ваш собственный API должен сам проверять права. Скрытая кнопка не мешает кому-то вызвать эндпоинт напрямую.
• Использование боевых ключей при тестировании. Используйте ключи тестового режима, пока не готовы к запуску.

Что попросить у AI-конструктора

• «Какие внешние API использует это приложение и сколько стоит каждый?»
• «Вызывай API платежей только с сервера. Читай ключ из переменной окружения.»
• «Перечисли все эндпоинты нашего API, что каждый делает и кому разрешено его вызывать.»
• «Проверяй на сервере, что вошедший пользователь владеет бронированием, прежде чем обновлять или удалять его.»
• «Если API почтового сервиса не отвечает, всё равно сохрани бронирование и запиши ошибку в лог.»
• «Пока используй тестовый режим провайдера.»

API в Mythex

Mythex может создать ваш собственный API — как часть веб-приложения или как отдельный бэкенд на Node, Python (FastAPI), C# или Java, работающий рядом с фронтендом, — и написать код, который вызывает сторонние сервисы. Ключи API вы добавляете как секреты проекта, а не в чат, и они становятся доступны приложению в предпросмотре и после публикации. В документации есть рецепты интеграции любого API и REST API-бэкенда.

Вопросы