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

В этой статье, я и мои коллеги хотим поделиться опытом по интеграции систем используя 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.

Расписание тренингов от Art of Business Analysis

Новости и статьи по бизнес-анализу - https://t.me/artofba