Описание требований к интеграции (часть 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 конечный пользователь один и тот же, но для реализации его в системе необходим разный набор параметров. Для сопоставления параметров можно использовать следующую таблицу: