top of page

Описание требований к интеграции (часть 2). API

Обновлено: 11 сент. 2023 г.

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


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


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


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

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


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

Итак, с чего стоит начать решение данной задачи. В первую очередь необходимо разобраться в наборе функциональных возможностей и логике их работы предоставляемой API. Для этого необходимо запросить документацию API, которая может быть представлена в разном виде: свободное описание на сайте компании, swagger схема, Postman коллекция и т.д., но должна содержать следующую информацию: способ аутентификации и авторизации, набор конечных точек с описанием формата запроса и ответа, описание зависимостей между методами, а также перечень возможных ошибок при работе с API. В нашем случае мы можем найти всю необходимую информацию в публичном доступе на сайте компании.

Давайте разберемся что же все это значит на конкретном примере.


Аутентификация – проверка пользователя на наличие доступа в систему. В нашем случае используется токен - уникальный идентификатор пользователя, сгенерированный в момент создания пользователя и чаще всего неизменный на протяжении всего жизненного цикла пользователя. Изменение токена пользователя приведет к потере доступа к API и необходимости его обновления в нашей системе для возобновления доступа.

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

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

Получить(GET) – для получения данных об аккаунте нашего пользователя мы можем использовать GET метод get_account_info .

Создать(POST) – для отправки сообщения пользователю мы можем использовать POST метод send_message.

Изменить(PUT) – используется для редактирования существующего объекта.

Удалить(DELETE) – используется для удаления существующего объекта.

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

Путь конечной точки – это URL, по которому доступен метод.

Формат тела запроса. Чаще всего в АПИ используются JSON и XML, подробнее о разнице между ними можно почитать здесь. В нашем примере используется JSON.

Набор входящих и исходящий параметров – это набор данных необходимый для выполнения метода и возвращаемых в результате работы метода.

Последовательность вызовов конечных точек. Так как АПИ - это набор простых действий, при работе с конечными точками необходимо понимать, в какой последовательности их необходимо вызывать. Например, для отправки сообщения пользователю необходимо чтобы пользователь предварительно подписался на наш Viber аккаунт. При нарушении последовательности вызовов конечных точек ответ будет содержать описание и код ошибки. Понимание данных зависимостей необходимо для моделирования процессов взаимодействия вашей системы с API.

После детального изучения логики работы API можно приступать к моделированию процессов взаимодействия систем. Для моделирования можем использовать диаграмму последовательностей UML, на которой необходимо отобразить все взаимодействующие системы или компоненты и смоделировать весь бизнес-процесс в разрезе обмена сообщениями. Принципиально не нужно выделять на диаграмме процессы и подпроцессы, сейчас нет задачи их декомпозировать. Наша задача - смоделировать все возможные потоки данных и определить перечень систем и/или компонентов, необходимых для предоставления необходимых данных или доступа к бизнес-логике. Например, рассмотрим процесс первого входа пользователя в систему:



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


После моделирования всех процессов, необходимо составить таблицу соответствия параметров используемых в интеграции. Т.к. интегрирующиеся системы чаще всего создаются разными командами или организациями для решения различных задач, то одинаковые по своей природе сущности реализовываются разными объектными моделями, учитывающими бизнес-задачу и контекст системы: и в нашей системе, и в Viber конечный пользователь один и тот же, но для реализации его в системе необходим разный набор параметров. Для сопоставления параметров можно использовать следующую таблицу:


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

Формат данных позволит выявить несоответствия форматов параметров в интегрирующихся системам и связанные с этим возможные проблемы при конвертации форматов либо потере данных из-за ограничения длинны строки.

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

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

Логика заполнения позволит явно определить способ обработки данных при наличии какого-либо несоответствия в системах, либо наличии сложной логики заполнения в одной из систем. Например, в вашей системе у одного пользователя может быть более одного телефонного номера, но только один из них помечен как «верифицирован в Viber».


На данном этапе, мы уже понимаем как и какие данные необходимо обрабатывать в процессе интеграции систем для достижения поставленной цели. Но в работе системы могут возникать ошибки, которые нужно научиться корректно обрабатывать. Если вы интегрируетесь с уже готовым API, то в спецификации должен быть определён перечень кодов и описание ошибок возможных при нарушении правил пользования АПИ. В нашем примере такой список уже есть, поэтому мы определяем какие ошибки потенциально могут быть воспроизведены пользовательскими действиями и описываем логику обработки данных ошибок нашей системой. Также ошибки могут воспроизводиться из-за большого количества запросов, поэтому необходимо составить прогноз количества запросов в единицу времени для каждой конечной точки на весь жизненный цикл вашей системы.


После определения зачем и как будет работать будущая интеграция необходимо задуматься о том, как после реализации мы будем выполнять отладку, оценивать и анализировать работу интеграции. Для решения этих задач можно использовать журналирование вызовов конечных точек, с сохранением URL, тела запроса, тела ответа и даты и времени вызова.


Описанные выше артефакты считаю достаточными для начала создания технического дизайна интеграции техническими специалистами вашей команды.


В следующей части статьи мы рассмотрим задачу проектирования API.




39 854 просмотра4 комментария

4件のコメント


Alexey Ulyashov
Alexey Ulyashov
2022年3月18日

Кирилл, спасибо за статью. Где можно посмотреть часть 3?

いいね!

Денис Федишен
Денис Федишен
2020年12月24日

"При интеграции с существующим API способ передачи параметром определён в спецификации..." - это не очевидно из статьи. Спецификация упомянута всего лишь один раз, где говорится про коды ошибок. Пример спецификации также можно привести в статье

いいね!

Кирилл Залата
Кирилл Залата
2020年12月23日

Денис, спасибо за комментарий 🙂

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

いいね!

Денис Федишен
Денис Федишен
2020年12月23日

Спасибо за статью! Есть вопрос: При вызове методов API, параметры запроса можно передавать как в теле запроса так и в самой строке URL. Было бы не плохо указать в каком случае как поступать?

いいね!
bottom of page