Вернуться к блогу
За привычным действием в цифровом продукте часто скрыта работа нескольких систем. Покупатель оформляет заказ в одном окне, но сведения о нем одновременно нужны складу, платежному сервису, CRM и службе доставки. Чтобы участники процесса обменивались командами и данными по единым правилам, используют API.
Пользователь не следит за технической цепочкой. Для него важен итог: актуальный остаток, подтвержденная оплата или рассчитанный маршрут. Приложения в это время обращаются друг к другу, проверяют доступ и возвращают результат в согласованном формате.
Разберем, что означает API, из каких частей складывается такое взаимодействие, чем отличаются REST, SOAP, GraphQL и gRPC и что проверить до подключения внешнего сервиса.
API, или Application Programming Interface – это заранее описанная граница взаимодействия между программами. Она определяет доступные операции, необходимые данные и форму результата.
Удобно представить API как окно приема документов. Внутренняя работа организации остается за ним: заявителю важно выбрать нужную услугу, передать комплект сведений по установленным правилам и получить ответ. Программа действует так же – обращается к разрешенной операции и не вмешивается во внутренние процессы другой системы.
Поэтому интернет-магазину не нужно знать, как платежный провайдер устроил проверку транзакции. Магазин передает предусмотренные контрактом параметры и получает подтверждение либо описание причины отказа.
Важно: API – не отдельная программа и не обязательно интернет-сервис. Программные интерфейсы есть у операционных систем, библиотек, браузеров, баз данных и облачных платформ. В этой статье основное внимание уделено веб-API, через которые системы обмениваются данными по сети.
API показывает доступные действия, принимает корректный запрос и возвращает результат, не раскрывая внутреннее устройство системы.
В веб-интеграции одна сторона инициирует обращение, а другая его обслуживает. Инициатором может быть сайт, приложение, касса или серверный модуль. Он направляет вызов по предусмотренному адресу, после чего принимающая система проверяет запрос и решает, можно ли выполнить операцию.
Допустим, посетитель открыл карточку товара. Клиентская часть запрашивает сведения по идентификатору, а сервер возвращает данные для экрана. При отсутствии позиции или прав доступа вместо карточки приходит результат с соответствующим статусом ошибки.
Весь обмен можно свести к шести шагам:
1. Клиент выбирает нужную операцию по адресу эндпоинта.
2. Метод сообщает системе характер действия с ресурсом.
3. Параметры, заголовки и тело передают контекст и данные.
4. Сервер проверяет структуру обращения, полномочия и ограничения.
5. Бизнес-логика выполняет операцию или фиксирует причину отказа.
6. Клиент интерпретирует статус и продолжает пользовательский сценарий.
HTTP задает общий смысл методов и групп кодов ответа. GET связан с чтением представления ресурса, а POST передает данные для обработки. Ответы с кодами 200-299 означают, что запрос выполнен успешно. Коды 400-499 указывают на проблему с запросом или доступом, а 500-599 – на ошибку при обработке запроса на стороне сервера.
Клиент отправляет структурированный запрос, API передаёт его сервису и возвращает результат или понятную ошибку.
Условный интернет-магазин может получить товар таким запросом:
GET /api/products/42 Authorization: Bearer Accept: application/json
В ответ сервер возвращает статус и данные:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 42,
"name": "Настольная лампа",
"price": 4990,
"available": true
}Если товара с таким идентификатором нет, сервер вернет ошибку:
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error": "product_not_found",
"message": "Товар с id 42 не найден"
}Это учебный пример. Реальный адрес, набор полей, способ авторизации и правила обработки ошибок определяются контрактом конкретного API.
Один URL еще не образует полноценный API. Рабочий контракт складывается из адресов операций, способов обращения к ним, структуры данных и правил обработки результата.
Элемент | Что означает | Пример |
Эндпоинт | Адрес доступной операции или ресурса | /api/orders/125 |
Метод | Намерение клиента | GET, POST, PUT, DELETE, PATCH |
Параметры | Уточняющие значения | номер страницы, фильтр, идентификатор |
Заголовки | Служебная информация | формат ответа, токен доступа |
Тело запроса | Данные для создания или изменения | состав заказа, контакт получателя |
Ответ | Статус, данные или описание ошибки | 200, JSON с заказом |
Документация | Правила интеграции | схемы, примеры, ограничения, версии |
Полезное описание интеграции не заканчивается перечнем полей. Из него должно быть понятно, какие значения обязательны, допустимо ли повторять вызов, как выглядит ошибка, какие действуют лимиты и что произойдет после выхода новой версии.
Для REST API часто используют спецификацию OpenAPI. Она задаёт машиночитаемый, независимый от языка формат описания операций и параметров. Такая спецификация помогает поддерживать документацию, генерировать клиентский код и проверять соответствие реализации договоренностям. Подробнее это описано в официальной спецификации OpenAPI.
Условия доступа помогают понять, кто вправе обращаться к интерфейсу и на каких основаниях. По этому признаку выделяют три распространенные модели.
Публичный API рассчитан на сторонних разработчиков и сопровождается открытыми правилами подключения. При этом доступ может зависеть от регистрации, ключа, тарифа и установленной квоты.
Партнерский API предназначен для конкретного круга компаний. С его помощью передают заказы, статусы, документы или данные программы лояльности, а перечень операций закрепляют договоренностями сторон.
Внутренний API обслуживает компоненты одного продукта или корпоративного контура. Внешним клиентам он недоступен, однако ему также нужны документация, разграничение прав, управление версиями и мониторинг.
Это деление описывает модель доступа, а не технологию передачи данных. И публичный, и внутренний интерфейс могут быть построены в стиле REST или на другой архитектуре.
API может связывать внутренние модули, партнерские системы или множество внешних приложений.
REST, SOAP, GraphQL и gRPC нельзя считать четырьмя полностью равнозначными «видами API». Они по-разному задают модель обращения, контракт и способ передачи данных.
Подход | Как устроен | Где часто применяют | Что учитывать |
REST | Архитектурный стиль вокруг ресурсов и единообразного интерфейса, часто поверх HTTP | веб-сервисы, мобильные приложения, внешние интеграции | важно согласовать ресурсы, методы, статусы и версии |
SOAP | Протокол обмена структурированными XML-сообщениями | корпоративные и унаследованные интеграции, системы со строгими контрактами | спецификации и сообщения объёмнее, но контракт может быть формализован очень подробно |
GraphQL | Язык запросов и среда выполнения, где клиент запрашивает нужный набор полей | интерфейсы со сложными связанными данными и разными клиентами | нужны контроль сложности запросов, кеширование и авторизация на уровне данных |
gRPC | Фреймворк удаленного вызова процедур, обычно с Protocol Buffers | взаимодействие внутренних сервисов и системы с требованиями к эффективности | браузерным клиентам часто нужен дополнительный слой, важны совместимость схем и инфраструктура |
API может быть реализован в стиле REST, но этим понятием не ограничивается. SOAP формализует обмен сообщениями, GraphQL дает клиенту контроль над составом выборки, а gRPC ориентирован на вызовы между сервисами. Подход выбирают по характеру данных, клиентам, ограничениям безопасности и условиям эксплуатации.
Понятие API шире веб-сервиса. Программный интерфейс встречается внутри библиотеки, браузера или операционной системы и может обходиться без сетевого обмена. Веб-сервис, напротив, предоставляет свои возможности удаленному клиенту через сеть.
Следовательно, веб-сервис открывает сетевой API, но не всякий API относится к веб-сервисам. Геолокационный интерфейс браузера работает с возможностями пользовательского устройства, а платежный провайдер принимает обращения интернет-магазина по сети.
Подробнее о серверной части и обмене между программами мы рассказали в статье «Что такое веб-сервис и как он работает».
API используется и в продуктах компаний, для которых разработка не является основным бизнесом.
При оформлении покупки интернет-магазин обращается сразу к нескольким контурам: проверяет остаток, запускает оплату, создает запись в CRM и передает сведения в доставку. Пользователь видит единый заказ, хотя его обслуживает цепочка независимых решений.
По такому же принципу банковское приложение собирает сведения об операциях, сервис доставки обновляет координаты курьера, а корпоративный портал синхронизирует сотрудников и документы с учетной системой.
Готовая интеграция экономит повторную разработку функции, но не отменяет проектирование. Нужно проверить качество документации, права на использование данных, лимиты, стоимость, доступность сервиса и поведение продукта при сбое внешней системы.
Один пользовательский заказ может вызвать несколько API-запросов к независимым системам.
Для бизнеса API ценен не сам по себе, а как управляемая точка связи между процессами и продуктами. При стабильном контракте компания получает несколько эффектов.
Автоматизация. Статус заказа, остатки и документы переходят между системами без ручного копирования.
Повторное использование функций. Один модуль оплаты или авторизации можно подключить к сайту, приложению и внутреннему порталу.
Быстрее проверяются гипотезы. Команда подключает готовую функцию и сосредотачивается на собственной ценности продукта.
Проще развивать экосистему. Партнёры получают контролируемый способ работать с разрешенными данными и операциями.
Разделяются зоны ответственности. Каждая система отвечает за свою логику, а контракт определяет границу взаимодействия.
Однако API не гарантирует экономию автоматически. Плохо спроектированный интерфейс создаёт зависимость от конкретной реализации, усложняет изменения и переносит ошибки между системами. Польза появляется, когда контракт стабилен, документирован и наблюдаем в эксплуатации.
Перед оценкой и разработкой интеграции стоит собрать ответы на несколько практических вопросов.
1. Сценарий. Какую бизнес-задачу решает обмен и что увидит пользователь при успехе или ошибке?
2. Контракт. Какие операции, поля, форматы и статусы предусмотрены?
3. Доступ. Как устроены аутентификация и авторизация, кто выдает и отзывает ключи?
4. Ограничения. Есть ли лимиты запросов, платные тарифы, квоты и ограничения по данным?
5. Надежность. Что делать при тайм-ауте, повторном запросе или временной недоступности партнёра?
6. Версии. Как поставщик предупреждает об изменениях и сколько поддерживает старый контракт?
7. Тестирование. Есть ли тестовая среда, примеры запросов и предсказуемые тестовые данные?
8. Наблюдаемость. Какие метрики, журналы и идентификаторы помогут найти проблемный запрос?
9. Ответственный. Кто поддерживает интеграцию с каждой стороны и как проходит разбор инцидентов?
Если хотя бы часть ответов неизвестна, оценка сроков будет ненадежной. Сначала лучше уточнить контракт и пограничные сценарии, а уже затем планировать разработку.
Через API могут выполняться операции с персональными данными, платежами и внутренними объектами. Поэтому безопасность не сводится к наличию ключа: сервер проверяет полномочия на каждое действие, выдает минимальный набор разрешений, валидирует входные данные, ограничивает частоту обращений и фиксирует значимые события.
Отдельный риск – ситуация, когда пользователь имеет доступ к API, но получает или изменяет чужой объект по подменённому идентификатору. В OWASP API Security Top 10 ошибки объектной авторизации стоят среди ключевых угроз. Проверка должна происходить на сервере для каждого запроса, а не только в интерфейсе приложения.
Логи тоже требуют осторожности. Они должны помогать расследовать сбой, но не содержать токены, пароли, платёжные реквизиты и лишние персональные данные.
Собственный API обычно нужен, если сайт, приложение, личный кабинет и внутренние системы должны использовать общую бизнес-логику или если продукт планирует партнёрские интеграции. Он также полезен, когда готовые сервисы не покрывают процесс, а ручной обмен файлами уже приводит к задержкам и ошибкам.
Начинать стоит не со списка методов, а со сценариев: кто обращается к системе, какое действие выполняет, какие данные для этого нужны и что должно произойти при отказе. На этапе системной аналитики команда проектирует модель данных, контракт, права доступа, версии и эксплуатационные требования.
В рамках веб-разработки команда Amiga помогает спроектировать серверную часть, интеграции и интерфейсы обмена данными под задачи продукта – от аналитики и технического задания до разработки, тестирования и запуска.
API – это описанный способ обращения одной программы к возможностям другой. Он определяет доступные операции, входные данные и форму результата.
Нет. API описывает доступные операции и формат взаимодействия, а интеграция реализует конкретный обмен между выбранными системами. В одном бизнес-сценарии могут участвовать несколько API.
Нет. Сервер может принимать обращения по веб-API, однако API обозначает правила взаимодействия, а не саму вычислительную систему. Программные интерфейсы также есть у библиотек, браузеров и операционных систем.
Нет. Веб-API обычно использует сеть, но программный интерфейс может работать локально внутри устройства, приложения или операционной системы.
REST API строит взаимодействие вокруг ресурсов и ограничений REST, чаще всего используя HTTP. API – более широкое понятие: кроме REST существуют SOAP, GraphQL, gRPC и другие варианты организации обмена.
Эндпоинт – точка обращения к определенному ресурсу или операции. Чтобы понять назначение вызова, адрес рассматривают вместе с HTTP-методом, параметрами и требованиями к доступу.
API задает понятную границу между системами: одна сторона знает, к какой операции обратиться и что передать, другая обязуется вернуть результат в согласованной форме. Поэтому единое действие в интерфейсе может запускать работу нескольких независимых сервисов.
Качественный API не ограничивается набором адресов. Ему нужны понятный контракт, документация, контроль доступа, обработка ошибок, версии, тестовая среда и мониторинг. Если продумать эти элементы до разработки, интеграция будет легче развиваться и поддерживаться после запуска.
