У цій статті я та мої колеги хочемо поділитися досвідом з інтеграції систем, використовуючи API.
Як і у попередній статті, варто одразу сказати, що опис вимог до інтеграції систем – стандартне завдання для системного чи бізнес-аналітика. Але ви можете зіткнутися зі складнощами, якщо раніше її не вирішували.
API - це програмний інтерфейс системи, який дозволяє будь-якій іншій зацікавленій системі отримати доступ до даних або бізнес-функцій.
Для початку розберемося у простій ситуації, коли необхідно інтегруватися з вже існуючим API, що надається сторонньою системою.
Припустимо, вам необхідно підвищити рівень безпеки вашої програми шляхом впровадження двофакторної автентифікації в системі. На етапі стратегічного аналізу, враховуючи безліч факторів, зацікавлені особи вирішили, що другим типом автентифікаційних даних буде числовий код, що передається в особистому повідомленні через Viber.
Варто зазначити, що це одне з багатьох завдань, яке можна вирішити шляхом інтеграції систем з використанням API, але цей приклад вважаю простим та достатнім для розуміння принципів інтеграції систем за допомогою API.
Отже, з чого варто розпочати вирішення цього завдання. В першу чергу необхідно розібратися у наборі функціональних можливостей, що надається API, та логікі їх роботи. Для цього необхідно запитати документацію API, яка може бути представлена в різному вигляді: вільний опис на сайті компанії, swagger-схема, колекція Postman тощо, але яка має містити наступну інформацію: спосіб автентифікації та авторизації, набір кінцевих точок з описом формату запиту та відповіді, опис залежностей між методами, а також перелік можливих помилок під час роботи з API. У нашому випадку ми можемо знайти всю необхідну інформацію у публічному доступі на сайті компанії. Давайте розберемося, що все це означає на конкретному прикладі.
Автентифікація – перевірка користувача на наявність у нього доступу до системи. У нашому випадку використовується токен - унікальний ідентифікатор користувача, згенерований в момент створення користувача і найчастіше незмінний протягом усього життєвого циклу користувача. Зміна токена користувача призведе до втрати доступу до API та необхідності його оновлення в нашій системі для відновлення доступу.
Авторизація – перевірка користувача на наявність доступу до певної дії. У нашому випадку залежно від налаштувань доступу у застосунку користувача, якому потрібно надіслати повідомлення, для нашої системи може бути обмежений доступ до персональних даних. Виявлення та аналіз прав доступу необхідні для валідації вимог до нашої системи у майбутньому.
Набір кінцевих точок (endpoints). Перелік функціональних можливостей API, реалізований набором різних типів дій: отримати, створити, змінити, видалити і т.д.
Отримати (GET) – для отримання даних облікового запису нашого користувача ми можемо використовувати GET метод get_account_info .
Створити (POST) – для надсилання повідомлення користувачу ми можемо використовувати метод POST send_message.
Редагувати (PUT) – використовується для редагування існуючого об'єкта.
Видалити (DELETE) – використовується для видалення існуючого об'єкта.
В описі кінцевої точки, окрім типу дії, вказується шлях, яким ця кінцева точка доступна, формат тіла запиту та відповіді, а також набір вхідних та вихідних параметрів.
Шлях кінцевої точки – це URL, по якому можна отримати доступ до методу.
Формат тіла запиту. Найчастіше у API використовуються JSON і XML, докладніше про різницю між ними можна почитати тут. У прикладі використовується JSON.
Набір вхідних та вихідних параметрів – це сукупність даних, необхідних для виконання методу, та даних, що повертаються внаслідок роботи методу.
Послідовність викликів кінцевих точок. Оскільки API - це набір простих дій, під час роботи з кінцевими точками необхідно розуміти, у якій послідовності їх потрібно викликати. Наприклад, для надсилання повідомлення користувачеві необхідно, щоб користувач попередньо підписався на наш обліковий запис у Viber. При порушенні послідовності викликів кінцевих точок відповідь міститиме опис та код помилки. Розуміння таких залежностей потрібне для моделювання процесів взаємодії вашої системи з API.
Після детального вивчення логіки роботи API можна розпочинати моделювання процесів взаємодії систем. Для моделювання можемо використовувати діаграму послідовностей (sequence diagram) UML, де необхідно відобразити всі взаємодіючі системи чи компоненти та змоделювати весь бізнес-процес у розрізі обміну повідомленнями. Принципово не потрібно виділяти на діаграмі процеси та підпроцеси, зараз немає завдання їх декомпозувати. Наше завдання – змоделювати всі можливі потоки даних та визначити перелік систем та/або компонентів, необхідних для надання необхідних даних або доступу до бізнес-логіки. Наприклад, розглянемо процес першого входу користувача до системи:
При моделюванні процесу необхідно враховувати, що на виконання запитів та обробку результатів буде витрачений певний час, а це може призвести до неможливості виконати наступний запит – детальніше про стан гонитви (race condition) можна почитати тут.
Після моделювання всіх процесів необхідно скласти таблицю відповідності параметрів, що використовуються в інтеграції. Системи, які інтегруються, найчастіше створюються різними командами чи організаціями для вирішення різних завдань, тому однакові за своєю природою сутності реалізуються різними об'єктними моделями, що враховують бізнес-завдання і контекст системи: і у нашій системі, і у Viber кінцевий користувач один і той самий, але для реалізації його у системі необхідний різний набір параметрів. Для порівняння параметрів можна використати наступну таблицю:
Назва параметрів дозволить виявити відсутні дані, визначити джерело заповнення запиту та спосіб зберігання інформації, отриманої у відповіді.
Формат даних дозволить виявити невідповідності форматів параметрів у системах, що інтегруються, та пов'язані з цим можливі проблеми при конвертації форматів або втраті даних через обмеження довжини рядка.
Приклад даних необхідний валідації відповідності реальних даних заданому формату. При заповненні необхідно використовувати крайні значення даних: найдовший рядок, дати або цілочисельні значення, що зберігаються у форматі рядка тощо. У результаті аналізу даних з реального середовища (prod environment) можуть з’явитися додаткові вимоги до даних у вашій системі, що у свою чергу призведе до додаткових витрат.
Перевірка обов'язковості заповнення параметра на рівні системи дозволить провалідувати можливість заповнення всіх обов'язкових у запиті полів та можливість збереження даних із відповіді з урахуванням обов'язкових полів у нашій системі.
Логіка заповнення дозволить явно визначити спосіб обробки даних за наявності будь-якої невідповідності в системах або наявності складної логіки заповнення в одній із систем. Наприклад, у вашій системі в одного користувача може бути більше одного телефонного номера, але лише один із них позначений як «верифікований у Viber».
На даному етапі ми вже розуміємо, як і які дані необхідно обробляти в процесі інтеграції систем для досягнення поставленої мети. Але в роботі системи можуть виникати помилки, які потрібно навчитися коректно обробляти. Якщо ви інтегруєтеся з вже готовим API, то у специфікації має бути визначений перелік кодів та опис помилок, можливих при порушенні правил користування API. У нашому прикладі такий список вже є, тому ми визначаємо які помилки потенційно можуть бути відтворені діями користувача і описуємо логіку обробки даних помилок нашою системою. Також помилки можуть відтворюватися через велику кількість запитів, тому необхідно скласти прогноз кількості запитів в одиницю часу для кожної кінцевої точки на весь життєвий цикл вашої системи.
Після визначення, навіщо і як працюватиме майбутня інтеграція, необхідно задуматися про те, як після реалізації ми виконуватимемо налагодження (debugging), оцінюватимемо та аналізуватимемо роботу інтеграції. Для вирішення цих завдань можна використовувати журналування дзвінків кінцевих точок, зі збереженням URL, тіла запиту, тіла відповіді та дати та часу дзвінка.
Описані вище артефакти вважаю достатніми для початку створення технічного дизайну інтеграції технічними фахівцями вашої команди.
У наступній частині ми розглянемо задачу проєктування API.
(переклад - Yevhen Kliukin, редактор - Denys Gobov)
Розклад тренінгів від Art of Business Analysis Новини та статті по бізнес-аналізу - https://t.me/artofba