Что такое API простыми словами: как сайты и приложения договариваются между собой

«Подключим оплату через API», «интеграция с CRM по API», «API временно недоступен» — эти фразы слышит каждый, кто заказывает сайт. Объясняем без кода, что такое API, где он уже работает на вашем сайте, что за ключ API просят никому не показывать и почему из-за чужого API может не работать оплата, хотя сам сайт открывается.

API (Application Programming Interface, программный интерфейс приложения) — это набор правил, по которым одна программа обращается к другой и получает от неё данные или действие. Через API сайт узнаёт у банка, прошла ли оплата, у службы доставки — сколько стоит везти посылку, у сервиса погоды — какая температура в городе. Человек с API напрямую не работает: он видит на экране только результат обмена.

Как работает API: официант между залом и кухней

API работает как официант в ресторане. Вы сидите в зале и не заходите на кухню: вы выбираете блюдо из меню, официант передаёт заказ поварам и приносит готовую тарелку. Как устроена кухня, кто и на какой плите готовит — вас не касается.

В интернете роли те же. Зал — ваш сайт или приложение. Кухня — чужая система: банк, склад, картографический сервис. Меню — документация API: что можно попросить и в каком виде придёт ответ. Заказ — запрос, тарелка — ответ. Официант — сам API: он принимает только то, что есть в меню, и приносит только то, что кухня согласилась отдать.

Отсюда главное свойство API: он показывает наружу не всю систему, а только разрешённый набор действий. Справочник MDN (документация Mozilla для веб-разработчиков) определяет API как набор правил, которые позволяют взаимодействовать с программой другой программе — в отличие от интерфейса для человека. Проще говоря, сайт — интерфейс для людей, API — интерфейс для программ, и у одного сервиса часто есть и то и другое: вы платите на странице банка, а ваш магазин в это же время спрашивает у банка по API, прошёл ли платёж.

Где API работает вокруг вас каждый день

На обычном сайте небольшой компании API задействован в пяти-семи местах, и почти все они чужие. Оплата картой, расчёт доставки, карта в контактах, вход через Госуслуги, СМС с кодом, погода в приложении — это запросы к другим компаниям, а не работа вашего сервера.

Главное из таблицы: во всех семи случаях сайт открывается, а ломается только функция, зависящая от чужого API. Последний случай самый коварный: ошибки на экране нет, а заявки теряются днями.

Кнопка «Войти через Госуслуги» при этом не передаёт сайту ваш пароль: сайт обращается к API ЕСИА (Единой системы идентификации и аутентификации) и получает только подтверждение личности и разрешённые данные. Так же работают кнопки VK ID и Яндекс ID: официант приносит только то, что есть в меню.

Чем API отличается от сайта и от «интеграции»

Сайт показывает данные человеку, API отдаёт те же данные программе, а интеграция — это готовая связка двух систем, построенная поверх API. Когда подрядчик говорит «сделаем через API», он имеет в виду: у сервиса есть официальный способ обращаться к нему программно, и мы напишем код, который этим способом пользуется.

Из таблицы видно: поломка сайта заметна сразу, а поломка интеграции может неделями оставаться незамеченной. Фраза «у сервиса нет API» означает, что программного входа нет: данные придётся переносить руками или файлами.

Рядом с API часто звучит слово «вебхук» (webhook). Это обмен в обратную сторону: не сайт спрашивает сервис, а сервис сам стучится на адрес сайта, когда что-то произошло. По документации ЮKassa, о прошедшем платеже сервис присылает сайту уведомление «payment.succeeded», сайт должен ответить кодом HTTP 200 («принял»), иначе ЮKassa повторяет попытки в течение 24 часов. Если сайт сутки не отвечал, часть оплаченных заказов останется в вашей системе «неоплаченной».

Что такое ключ API и почему его нельзя показывать

Ключ API — это длинная строка из букв и цифр, которую сервис выдаёт при подключении и которую ваш сайт прикладывает к каждому запросу. По ключу сервис понимает, кто обращается, считает запросы, следит за лимитами и может отключить нарушителя.

В ресторанной аналогии ключ — клубная карта, на которую официант записывает заказы: без неё не обслужат, а с ней всё съеденное запишут на ваш счёт. По справочнику MDN, ключ нужен, чтобы владелец API знал, кто им пользуется, и мог отозвать доступ при злоупотреблении. Получают ключ в личном кабинете сервиса: по документации API Яндекс Погоды, ключ появляется в аккаунте после выбора тарифа и его оплаты.

Тот, кто получил ваш ключ, может тратить ваш баланс на СМС-шлюзе, рассылать спам от имени компании или читать данные клиентов в CRM. Чаще всего ключи утекают не через взлом, а через быт: скриншот настроек в рабочем чате, ключ в письме подрядчику, копия кода сайта в открытом репозитории.

Почему сайт открывается, а оплата или форма — нет

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

Причины делятся на три группы. Первая — упал сам чужой сервис: авария, перегрузка, плановые работы. Вторая — сломалась связка на вашей стороне: истёк ключ, кончился баланс СМС-шлюза, исчерпан месячный лимит запросов, разработчик изменил поля формы, и CRM перестала их понимать. Третья — сервис отключил старую версию API: сайт годами работал сам по себе, а письма о переходе на новую версию приходили на почту уволившегося сотрудника.

Внешне все три группы выглядят похоже. Кнопка долго крутится — сайт ждёт ответа и не дожидается. Ошибка 502 или 504 — промежуточный сервер не получил ответ от следующего звена; эти коды разобраны в статьях про ошибку 502 Bad Gateway и про коды ответа HTTP. Сообщение «Сервис временно недоступен» чаще всего пишет ваш же сайт, когда не смог достучаться до чужого API.

Как понять, что проблема в API, без консоли и программиста

Достаточно трёх наблюдений: открывается ли страница, какая именно функция не работает и что пишет страница статуса сервиса-поставщика. Если страница открывается, а не работает одна функция, завязанная на внешний сервис, проблема почти наверняка в API или в связке с ним.

Самая коварная строка таблицы — вторая: заявки перестали доходить до CRM, а на сайте никаких признаков. Поэтому раз в неделю полезно отправлять тестовую заявку самому себе. Страница статуса есть у большинства крупных сервисов: она находится поиском по запросу «название сервиса статус» и показывает, идёт ли сейчас авария.

Частые вопросы

API — это программа или сайт? Ни то ни другое. API — договорённость о том, как к программе обращаться: по какому адресу, что можно попросить и в каком виде придёт ответ. Сама программа стоит за этой дверью, а сайт — соседняя дверь для людей. У банка могут быть приложение, сайт и API, и все три ведут к одной системе.

Нужен ли API моему сайту, если я ничего не программирую? Он у вас уже есть. Счётчик посещений, форма с отправкой в почту или CRM, кнопка оплаты и карта проезда работают через API соответствующих сервисов. Вопрос не в том, нужен ли он, а в том, знаете ли вы, какие внешние сервисы держат ваш сайт на плаву.

Что значат слова REST и JSON, которые говорит разработчик? REST — самый распространённый способ устроить API: программа отправляет обычные веб-запросы на определённые адреса, почти как браузер открывает страницы, только вместо страницы получает данные. JSON — текстовый формат этих данных: пары «название — значение», например «"status": "paid"». Программы читают его легко, а человек при желании тоже разберёт.

API всегда платный? Нет, но бесплатным он бывает до определённого объёма. Многие сервисы дают бесплатный лимит запросов, а сверх него берут плату за запросы или продают доступ по тарифу — так устроен, например, API Яндекс Погоды. Платёжные сервисы обычно не берут денег за сам API, а зарабатывают на комиссии с платежей.