Архитектурный стиль или протокол? Что нужно знать аналитику для работы с API

Привет Хабр! Меня зовут Татьяна Ошуркова, я разработчик, аналитик и автор телеграм-канала IT Talks. В процессе решения задач по интеграции систем в проработке требований на этапе системного анализа важно учесть множество аспектов, которые относятся к различным уровням реализации.

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

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

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

25 декабря я проведу бесплатный вебинар: «Разработка требований к интеграции в практической задаче», где мы рассмотрим проработку и описание требований на практике с реальным кейсом. Запись на вебинар доступна по ссылке.

API (Application Programming Interface) – это программный интерфейс, который определяет правила и механизмы взаимодействия между различными программными компонентами. По сути, API позволяет одной системе «общаться» с другой, предоставляя стандартизированный способ обмена данными и вызова функций.

API играет ключевую роль в реализации архитектурных стилей, использовании сетевых протоколов и организации типов интеграций между системами. Каждая из этих категорий влияет на дизайн API и определяет способ взаимодействия между компонентами.

Архитектурные стили API

Архитектурный стиль задает общий подход к построению взаимодействий между клиентом и сервером. К архитектурным стилям можно отнести REST, GraphQL и с некоторой точки зрения даже SOAP, который в теории называется протоколом.

REST (Representational State Transfer)

REST – это архитектурный стиль для создания распределённых систем, таких как веб-сервисы. Основные принципы REST заключаются в следующем:

• Ресурсы. Всё представлено как ресурсы, идентифицируемые через URI.

• HTTP-методы. Используются стандартные методы (GET, POST, PUT, DELETE) для работы с ресурсами.

• Отсутствие состояния. Каждый запрос самодостаточен и не зависит от предыдущих.

• Кешируемость. Ответы могут быть кешированы для повышения производительности.

• Единообразие интерфейса. Стандартизированные взаимодействия между клиентом и сервером (например, через JSON).

Рассмотрим пример API для управления заказами:

GET /orders         - Получить список заказов   POST /orders        - Создать новый заказ   PUT /orders/{id}    - Обновить заказ   DELETE /orders/{id} - Удалить заказ  

Можно построить диаграмму последовательности взаимодействия компонентов системы с использованием REST API, которая иллюстрирует последовательность операций для создания нового пользователя (POST запрос) и получения данных о пользователе (GET запрос):

GraphQL

GraphQL – это язык запросов для API и среда выполнения для обработки этих запросов. Он предоставляет более гибкий способ взаимодействия с API по сравнению с REST. В отличие от REST, где запросы ограничены набором фиксированных эндпоинтов, GraphQL позволяет клиенту точно определить, какие данные ему нужны, и получить их в одном запросе.

REST использует HTTP-методы для работы с ресурсами через отдельные эндпоинты. Явная схема для API отсутствует. GraphQL, напротив, опирается на строго типизированную схему, которая описывает данные и операции (запросы, мутации, подписки). Клиент отправляет запросы на единый эндпоинт и сам определяет, какие данные ему нужны, что позволяет минимизировать избыточность и число запросов. Изменения добавляются в схему без необходимости версионирования. Основные особенности GraphQL:

• Единый эндпоинт. Все запросы отправляются на один URL.

• Гибкость запросов. Клиент может запрашивать только нужные поля.

• Типизация. Все данные строго типизированы с использованием схем.

• Мутации. Возможность изменять данные через специальные запросы (например, создание, обновление, удаление).

• Подписки. Поддержка обновлений данных в реальном времени.

Рассмотрим пример схемы:

type User {   id: ID!   name: String!   email: String! }  type Query {   getUser(id: ID!): User }  type Mutation {   createUser(name: String!, email: String!): User }

А также рассмотрим пример запроса и диаграмму последовательность для отображения взаимодействия компонентов системы:

query GetUser {   getUser(id: "1") {     id     name     email   } }

SOAP

SOAP (Simple Object Access Protocol) – это протокол для обмена структурированными сообщениями в распределённых системах, основанный на XML. Его называют протоколом из-за его строгой спецификации (включая формат сообщений и обработку ошибок). Однако он также описывает принципы взаимодействия и может рассматриваться как стиль, если акцентировать внимание на концепции. SOAP использует HTTP, SMTP или другие транспортные протоколы для передачи сообщений и широко применяется для взаимодействия между различными приложениями и сервисами в веб-разработке. Основные особенности SOAP:

• Формат. XML-основанный формат для сообщений.

• Протоколы. Работает через разные транспортные протоколы (HTTP, SMTP и другие).

• Структура. Строгая структура сообщений с элементами Envelope, Header и Body.

Рассмотрим пример SOAP-запроса, а также диаграмму последовательности взаимодействия компонентов с его использованием:

<?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"                   xmlns:ord="http://www.example.org/orders">    <soapenv:Header/>    <soapenv:Body>       <ord:CreateOrder>          <ord:customerId>456</ord:customerId>          <ord:items>             <ord:item>                <ord:productId>123</ord:productId>                <ord:quantity>2</ord:quantity>             </ord:item>          </ord:items>       </ord:CreateOrder>    </soapenv:Body> </soapenv:Envelope>

RPC

RPC (англ. Remote Procedure Call в переводе Удалённый вызов процедур) – это архитектурный стиль, позволяющий одной программе вызывать функции или методы другой программы, которая может находиться на другом сервере или устройстве, как будто это локальный вызов. RPC скрывает детали сетевого взаимодействия, предоставляя разработчикам иллюзию работы с локальными процедурами.

Основная идея RPC заключается в том, что клиент отправляет запрос на выполнение функции на сервере, а сервер обрабатывает запрос, выполняет соответствующую функцию и возвращает результат. Основные особенности:

• Прозрачность вызовов. Разработка не взаимодействуют напрямую с сетевым уровнем, а работают с интерфейсами.

• Синхронное взаимодействие. Клиент ожидает ответа от сервера. (Хотя есть и асинхронные реализации.)

• Строгая типизация. Функции и их параметры описаны в интерфейсе (IDL, Interface Definition Language).

• Используемые протоколы. Реализации RPC могут использовать разные протоколы передачи данных, например HTTP, TCP или бинарные форматы.

Допустим, нам необходимо получить информацию о пользователе по ID. В RPC взаимодействие выглядит так:

1. Client вызывает функцию getUserById(userId) через локальный интерфейс.

2. RPC Stub (прокси на стороне клиента) сериализует запрос и отправляет его на сервер.

3. RPC Server принимает запрос, десериализует его и вызывает соответствующую процедуру.

4. После обработки запроса сервер возвращает результат клиенту через Stub.

Протоколы API

Протоколы API – это набор правил и механизмов, которые определяют, как программные приложения или их компоненты взаимодействуют друг с другом. Они предоставляют стандартизированные методы для обмена данными и вызова функций между клиентами (например, приложениями, браузерами) и серверами.

В отличие от архитектурных стилей, которые описывают подход к проектированию (принципы взаимодействия и организации данных), протоколы детализируют, каким образом происходит взаимодействие, включая формат сообщений, процесс передачи данных и обработку ошибок. Рассмотрим несколько наиболее часто используемых.

HTTP/HTTPS (HyperText Transfer Protocol)

Один из наиболее популярных протоколов, используется для передачи данных. Он построен на модели запрос-ответ, где клиент отправляет запрос к серверу, а сервер возвращает ответ.

• Основа для большинства веб-сервисов.

• Поддерживает методы: GET, POST, PUT, DELETE и другие.

• HTTPS (с шифрованием SSL/TLS) обеспечивает безопасность передачи данных

WebSocket

Протокол для двусторонней связи в реальном времени. В отличие от HTTP, WebSocket позволяет серверу инициировать связь с клиентом (push-уведомления).

• Используется для приложений с высокой частотой обновления данных (чаты, биржи).

• Постоянное соединение между клиентом и сервером.

gRPC (Google Remote Procedure Call)

Протокол удалённого вызова процедур, разработанный Google. Использует HTTP/2 для передачи данных, а сообщения структурированы в формате Protobuf (Protocol Buffers).

• Быстродействие благодаря бинарному формату.

• Поддерживает стриминг данных.

• Используется для микросервисов.

Типы интеграций по API

Различные способы интеграций систем по API описывают способы взаимодействия систем для передачи данных и выполнения операций. Это классификация интеграционных подходов, которая отражает, как именно организовано взаимодействие между системами или компонентами с учётом их архитектуры, сценариев использования и требований к производительности.

Прямая интеграция (Point-to-Point Integration)

Прямая интеграция подразумевает, что одна система (клиент) напрямую взаимодействует с другой системой (сервер) через API. Это наиболее простой и распространённый способ интеграции.

• Используется для синхронных вызовов, когда клиент ожидает мгновенного ответа.

• Часто реализуется через REST API, gRPC или GraphQL.

• Подходит для небольших приложений или сценариев с ограниченным числом взаимодействий.

Интеграция через API Gateway

API Gateway – это центральная точка входа для всех запросов к микросервисам. Она используется для маршрутизации запросов, обеспечения безопасности, кэширования и балансировки нагрузки.

• Подходит для микросервисных архитектур, где есть множество небольших независимых сервисов.

• Обеспечивает единый интерфейс для клиентов.

• Может комбинировать результаты нескольких запросов к микросервисам в один ответ.

Интеграция через Webhooks

Webhooks используются для асинхронного уведомления одной системы другой о произошедшем событии. В отличие от классических API, взаимодействие инициируется сервером, а не клиентом.

• Используются для уведомлений о событиях, таких как обновление статуса заказа или получение платежа.

• Работают через HTTP-запросы (обычно POST).

Подведём итоги

Можно сказать, что архитектурные стили, протоколы и типы интеграций — три взаимосвязанных аспекта, которые определяют, как системы взаимодействуют друг с другом через API.

Архитектурные стили задают правила проектирования взаимодействий, определяют, как данные структурируются и передаются между системами. Например, REST акцентирует внимание на использовании стандартов HTTP и работе с ресурсами через CRUD-операции, а GraphQL позволяет клиенту задавать структуру данных, которые он хочет получить.

Протоколы обеспечивают техническую основу передачи данных между системами. Они описывают, как информация передаётся на низком уровне: через HTTP, TCP, WebSocket и другие механизмы. Это конкретная реализация передачи данных, которая может поддерживать один или несколько архитектурных стилей.

Типы интеграций определяют общий способ взаимодействия систем: например, через посредников (API Gateway) или асинхронно (через webhooks). Типы интеграций выбираются на основе задач, масштабируемости и уровня независимости систем.

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

Желаю удачи в решении интеграционных задач и работе с API!