Описание требований к интеграции (часть 2). API
(Из ленты Курсы бизнес анализа, тренинги и обучение бизнес аналитике| ArtofBA)
В этой статье, я и мои коллеги хотим поделиться опытом по интеграции систем используя 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»:
Онлайн:
Комплексный онлайн тренинг по бизнес-анализу (40 PD hours)
Power BI: Создание решения для бизнеса (16 часов)
Data Science и машинное обучение для бизнес-аналитиков (16 часов)
Оффлайн:
Комплексный тренинг по бизнес-анализу (40 PD hours)