Интеграция и API
Ключевые тезисы
- Интеграция — это объединение систем для обеспечения их взаимодействия с целью обмена данными или функциональностью.
- API (Application Programming Interface) — это набор правил (контракт), по которым два программных компонента взаимодействуют друг с другом.
- REST — архитектурный стиль взаимодействия через HTTP, основанный на концепции ресурсов.
- SOAP — строго регламентированный протокол для обмена структурированными сообщениями, часто используемый в госпроектах и FinTech.
Понятие и виды интеграции
Интеграция — это объединение систем в целях обеспечения их взаимодействия для получения данных и/или функциональности (например, перевод денег через приложение с интеграцией с СБП).
Основные виды интеграций:
- Файловый обмен: Примитивный, синхронный способ. Системы обмениваются файлами произвольного формата и размера.
- Минус: Необходимость ручного обновления логики обработки в системе-приёмнике при изменении структуры файла.
- Общая база данных: Системы используют единый источник данных (общую БД).
- Плюс: Отсутствие сложных механизмов синхронизации.
- Минусы: Риск блокировок при конкурентном доступе, разрастание схемы БД, нарушение нормализации.
- Применение: Для частых запросов с небольшим объёмом данных.
- Обмен сообщениями: Асинхронный способ взаимодействия через отправку и получение сообщений.
- Инструменты: Брокеры сообщений (Kafka) или корпоративная шина.
- Применение: Для высоконагруженного обмена небольшими данными, где важна гарантия доставки.
- Удалённый вызов процедур (RPC): Одна система вызывает функции другой системы. Включает множество подходов (REST, SOAP, gRPC, GraphQL).
Технологии RPC
- REST: Архитектурный стиль поверх HTTP.
- SOAP: Строго регламентированный протокол.
- GraphQL: Технология для запроса строго необходимого набора данных (запросы и мутации).
- gRPC: Разработка Google на основе HTTP/2, использует бинарный формат Protocol Buffers для высокой скорости. Применяется во внутренних высоконагруженных системах.
- Webhook: Механизм для асинхронного взаимодействия по принципу "я отправлю запрос, а ты сама сообщишь, когда будешь готова".
- WebSocket: Технология для соединения в режиме реального времени (чаты, видеочаты).
Что такое API?
Программный интерфейс приложения (API) — это набор правил, по которым два программных компонента могут взаимодействовать друг с другом (контракт).
Роль в архитектуре:
Клиенты (веб-браузер, мобильное приложение) через API обращаются к API Gateway, который обеспечивает аутентификацию, авторизацию и маршрутизацию запросов к внутренним микросервисам. Те, в свою очередь, предоставляют свою функциональность через свои API.
Что входит в описание (контракт) API:
- Входные и выходные данные запросов.
- Ошибки и их коды.
- Требования к аутентификации и авторизации.
Важность API:
- Экономия времени и ресурсов за счёт использования готовой функциональности других систем.
- Стандартизация, способствующая развитию и масштабированию системы.
Архитектурный стиль REST
REST (Representational State Transfer) — это архитектурный стиль взаимодействия между клиентом и сервером через HTTP протокол.
Ключевое понятие: Ресурс — любая сущность, к которой можно получить доступ через API (заказ, товар, пользователь). Доступ осуществляется по уникальному URL.
Принципы REST:
- Клиент-серверная архитектура: Чёткое разделение ответственности.
- Отсутствие состояния (Stateless): Сервер не хранит контекст предыдущих запросов клиента. Каждый запрос самодостаточен.
- Кэширование: Возможность сохранять ответы для снижения нагрузки и увеличения скорости.
- Единообразие интерфейса:
- Ресурсы имеют чёткую структуру и уникальные идентификаторы (URI).
- Используются стандартные HTTP-методы.
- Данные передаются в предсказуемых форматах (JSON, XML).
- Многоуровневая система: Компоненты системы зависят только от соседних, что повышает устойчивость.
- Код по требованию (опционально): Сервер может передавать исполняемый код клиенту (например, JavaScript).
Структура URL в REST:Протокол://Хост[:Порт]/Путь/к/ресурсу?Параметры=запроса
- Параметры запроса (query parameters) подходят для передачи небольших данных (есть ограничение на длину URL).
Структура HTTP-запроса:
- Метод (GET, POST, PUT, DELETE).
- Заголовки (Headers): Метаданные (тип контента, информация о клиенте).
- Тело запроса (Body): Передаваемые данные (для POST, PUT).
Основные HTTP-методы (соглашение):
- GET: Получение ресурса.
- POST: Создание ресурса.
- PUT: Перезапись или создание ресурса (идемпотентный).
- DELETE: Удаление ресурса.
Фактическая логика обработки методов определяется разработчиком.
Протокол SOAP
SOAP (Simple Object Access Protocol) — строгий протокол для обмена структурированными сообщениями, популярный в корпоративной среде, госпроектах и FinTech.
Особенности:
- Жёстко регламентирует схему и функционал веб-сервиса.
- Взаимодействие описывается контрактом на основе двух файлов:
- WSDL (Web Services Description Language): Описывает функции (операции), предоставляемые сервисом, и структуру сообщений.
- XSD (XML Schema Definition): Описывает структуру и типы данных в запросах и ответах.
Пример взаимодействия:
Запрос и ответ являются XML-документами с чёткой структурой, определённой в WSDL и XSD.
Практика работы с API для аналитика
В проекте с существующей системой:
- Изучить документацию к текущим API (Swagger, WSDL).
- Проанализировать атрибутивный состав запросов/ответов.
- При доработке: дополнить существующие схемы данных или коды ошибок, если это необходимо.
При проектировании новой функциональности (фичи) с нуля:
- Выделить ресурсы, которыми будет оперировать сервис.
- Спроектировать эндпоинты (URL + HTTP-метод) для операций над ресурсами (создание, чтение, обновление, удаление).
- Определить атрибутивный состав для тела запроса и ответа.
- Спроектировать обработку ошибок: определить возможные коды состояния (например, 200 OK, 400 Bad Request) и детальные коды бизнес-ошибок с их описанием для потребителя API.