Урок 6 из 8 · 25 мин · обновлено

Интеграции и API: как системы обмениваются данными

Зачем системам интеграции, как аналитик описывает REST API: метод, адрес, параметры, тело запроса и ответа в JSON, коды ошибок, — что такое спецификация OpenAPI и синхронный и асинхронный обмен.

Зачем интеграции

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

Основа интеграций — API: договорённость, какие запросы одна система может отправить другой и что получит в ответ. Что такое API, HTTP-методы, коды ответа и JSON, разобрано в курсе «Postman и API для начинающих». Здесь — как аналитик описывает API для разработчиков.

Описание метода API

Возьмём метод начисления баллов в системе лояльности. Описание метода:

Назначение: начислить гостю баллы за выданный заказ.

Метод и адрес: POST /api/v1/accruals

Тело запроса:

Поле Тип Обязательно Описание Пример
guestId строка да идентификатор гостя "g-1042"
orderId строка да идентификатор заказа "o-5531"
amount число да сумма, оплаченная деньгами, в рублях 310
JSON
{
  "guestId": "g-1042",
  "orderId": "o-5531",
  "amount": 310
}

Успешный ответ — 201 Created:

JSON
{
  "accrualId": "a-88120",
  "points": 15,
  "balance": 135
}

Ошибки:

Код Когда Что делает приложение
400 не хватает поля или сумма меньше 0 ошибка в нашей системе, пишем в лог и разбираемся
404 гость не найден в системе лояльности создаём гостя методом регистрации и повторяем
409 за этот заказ баллы уже начислены считаем начисление успешным, повторно не начисляем
500, таймаут сбой у партнёра повторяем через 5 минут, до 12 раз, потом задача в поддержку

Ошибки — самая важная часть описания. Код 409 защищает от двойного начисления, если запрос случайно отправили дважды.

Синхронно и асинхронно

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

Если начисление сделать синхронным, медленная система лояльности задержит подтверждение заказа для гостя. Аналитик решает это вместе с разработчиками и фиксирует в требованиях.

OpenAPI

Описания методов в таблицах удобны для обсуждения, но стандартный формат для REST API — OpenAPI: файл YAML или JSON, где описаны все методы, поля и ответы. По нему автоматически строится документация Swagger, генерируется код и проверки. Многие аналитики пишут OpenAPI сами или проверяют то, что написали разработчики.

Перед тем как отдавать описание, аналитик сам отправляет запросы на тестовый сервер — например, в Postman — и проверяет, что ответы совпадают с описанием.

Попробуйте сами. Опишите метод «Получить баланс гостя» в системе лояльности: назначение, метод и адрес, параметры, пример успешного ответа и 2–3 ошибки.

Пример

Назначение: получить текущий баланс баллов гостя перед оплатой.

Метод и адрес: GET /api/v1/guests/{guestId}/balance, где guestId — идентификатор гостя.

Успешный ответ — 200 OK:

JSON
{
  "guestId": "g-1042",
  "balance": 135,
  "pending": 15
}

pending — баллы, которые ещё ожидают начисления: заказ оплачен, но не выдан.

Ошибки:

  • 404 — гость не найден: показываем баланс 0 и предлагаем вступить в программу;
  • 401 — неверный ключ доступа нашей системы: ошибка настройки, пишем в лог и сообщаем дежурному;
  • таймаут больше 2 секунд — показываем «Баллы временно недоступны», оплату не блокируем.

Метод синхронный: баланс нужен гостю прямо на экране оплаты.

Мини-тест: проверьте себя

Закрепите урок: несколько вопросов, разбор ответов — в конце.

  1. Что обязательно описать в методе API, кроме успешного ответа?

  2. Система лояльности отвечает долго, а гость ждёт подтверждения заказа. Что разумно предложить?

  3. Что такое OpenAPI?