API — это договорённый способ, которым одна программа просит другую что-то сделать или отдать данные: ваш сайт спрашивает платёжный сервис «оплачен ли заказ?» и получает ответ в понятном машине формате. Бизнесу API нужен, чтобы системы — сайт, 1С, CRM, маркетплейс, мессенджеры — обменивались данными сами, без ручного копирования. Перед интеграцией важно выяснить, где хранятся ключи доступа, что происходит при сбое и кто следит за лимитами.
После материала вы сможете
- объяснить, что такое API, эндпоинт, метод и код ответа, на примере ресторана и онлайн-оплаты
- перечислить правила обращения с ключами и токенами: где их хранить, кому не передавать, когда перевыпускать
- отличить запрос к API от вебхука и объяснить, что означает ответ 429 Too Many Requests
- задать подрядчику вопросы перед интеграцией по чек-листу из семи пунктов
Что знать заранее
Содержание
API — это меню и официант между программами
Вернёмся к ресторану из статьи о том, как устроен сайт. Гость не заходит на кухню и не берёт продукты сам: он открывает меню, выбирает блюдо и передаёт заказ официанту. Меню — это документация API: список того, что можно заказать и в каком виде. Официант — сам API: он принимает заказ по правилам, относит его на кухню и возвращает результат. Кухня — чужая система, устройство которой вам знать не нужно.
Аббревиатура расшифровывается как Application Programming Interface — программный интерфейс приложения. Как поясняет MDN, это набор функций и правил, через которые одна программа пользуется возможностями другой. Если интерфейс сайта сделан для людей, то API — интерфейс для программ.
Запрос и ответ: как разговаривают программы
Большинство веб-API работает поверх того же протокола HTTP, по которому браузер получает страницы. Разговор всегда состоит из запроса и ответа. Вот из чего складывается один запрос:
Адрес — эндпоинт
Конкретный адрес, отвечающий за одно действие: например, отдельный адрес для заказов и отдельный — для товаров. Эндпоинт — это строка меню.
Метод
Глагол запроса: получить данные, создать запись, изменить или удалить. Стандартные методы HTTP описаны в документации MDN.
Ключ доступа
Подтверждение, что запрос отправила ваша система, а не посторонний.
Данные
Что именно вы передаёте: номер заказа, телефон клиента, состав корзины.
Ответ с кодом
Система возвращает результат и числовой код: всё прошло успешно, запись не найдена, нет доступа или запросов слишком много.
GET
- Что делает
- Получить данные
- Пример в бизнесе
- Узнать остаток товара на складе
POST
- Что делает
- Создать новую запись
- Пример в бизнесе
- Передать заявку с сайта в CRM
PUT / PATCH
- Что делает
- Изменить существующую запись
- Пример в бизнесе
- Поменять статус заказа на «отгружен»
DELETE
- Что делает
- Удалить запись
- Пример в бизнесе
- Снять отменённую бронь
Данные чаще всего передаются в формате JSON — простом текстовом формате, который описан в стандарте IETF RFC 8259 и легко читается и программами, и людьми. Ответ о заказе может выглядеть так: {"order": 1042, "status": "paid"}. Это пары «название — значение», как строки в анкете.
Ключи и токены: как чужая система узнаёт вас
Чтобы ответить, система должна понять, кто спрашивает и что ему разрешено. Для этого при подключении выдают ключ API или токен — длинную строку символов, которую ваш сервер прикладывает к каждому запросу. Это как пропуск сотрудника: охрана не знает вас в лицо, но видит действующий пропуск.
Многие API используют так называемые bearer-токены. Стандарт RFC 6750 прямо предупреждает: любой, у кого оказался такой токен, может им пользоваться. Поэтому с ключами обращаются как с паролями от банка.
- Ключи хранятся только на сервере — во фронтенде их может увидеть любой посетитель
- Ключи не пересылают в мессенджерах и не вставляют в общие документы
- Для каждой интеграции — свой ключ с минимально нужными правами
- Ключи выпускают в личном кабинете сервиса, оформленном на компанию
- После ухода подрядчика или сотрудника ключи перевыпускают
Спрашивать или получать уведомления: REST и вебхуки
Самый распространённый стиль веб-API называют REST: данные представлены как ресурсы со своими адресами, а действия над ними выполняются стандартными методами HTTP. В REST инициатива у вас: ваша система сама приходит и спрашивает. Вебхук работает наоборот — чужая система сама присылает сообщение на ваш адрес, когда что-то произошло.
Запрос (вы спрашиваете)
- Ваш сервер обращается к сервису, когда нужны данные
- Подходит для справок: остатки, курсы, статус по запросу
- Если спрашивать слишком часто, можно упереться в лимит
- Если спрашивать редко, данные запаздывают
Вебхук (вам сообщают)
- Сервис сам отправляет уведомление на ваш адрес
- Подходит для событий: оплата прошла, пришёл заказ
- Ваш сервер должен быть доступен и уметь проверить подлинность сообщения
- Нужен план на случай, если уведомление потерялось
У большинства сервисов есть лимиты — сколько запросов можно отправить за минуту или за сутки. При превышении сервер отвечает кодом 429 Too Many Requests: этот код описан в стандарте RFC 6585, а MDN называет такой механизм ограничением частоты запросов (rate limiting). Хорошая интеграция умеет подождать и повторить запрос, а не теряет данные.
Где API встречается в бизнесе
Онлайн-оплата
- Что делает API
- Создаёт платёж и сообщает о результате
- На что обратить внимание
- Подтверждение оплаты — по вебхуку и проверке на сервере, а не по возврату клиента на сайт
Учёт в 1С
- Что делает API
- Передаёт заказы, остатки и цены между сайтом и учётом
- На что обратить внимание
- Кто источник правды для каждого поля и как часто идёт обмен
Маркетплейс, например Kaspi
- Что делает API
- Забирает заказы и обновляет цены и наличие
- На что обратить внимание
- Правила и ограничения конкретной площадки по её документации
Карты и адреса
- Что делает API
- Подсказывает адреса, считает расстояние для доставки
- На что обратить внимание
- Лимиты бесплатного использования и условия сервиса
Мессенджеры
- Что делает API
- Отправляет уведомления, принимает сообщения от бота
- На что обратить внимание
- Чей аккаунт бота и кто владеет его токеном
CRM
- Что делает API
- Создаёт сделку из заявки с сайта
- На что обратить внимание
- Что происходит с заявкой, если CRM временно недоступна
Подробно о двух самых частых интеграциях в Казахстане мы писали отдельно — об интеграции с Kaspi и о связке 1С с веб-приложением. Общий принцип везде один: сначала договориться, какая система главная для каждого типа данных, и только потом строить обмен.
Что спросить у подрядчика перед интеграцией
- Есть ли у сервиса официальная документация API и какую версию вы используете
- Где будут храниться ключи и токены и на кого оформлен кабинет сервиса
- Как интеграция поведёт себя, если чужой сервис недоступен или ответил ошибкой
- Как учитываются лимиты запросов и что будет при их превышении
- Как проверяется подлинность входящих вебхуков
- Куда записываются ошибки обмена и кто получит уведомление о сбое
- Что нужно поменять, если сервис выпустит новую версию API
Хорошая интеграция незаметна, пока работает, и громко сообщает о себе, когда что-то пошло не так. Плохая — наоборот.
