Система управления проектированием API банка: от создания интерфейса до импорта спецификации

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

Привет, Хабр! Меня зовут Алексей Тарасов, я ведущий аналитик IBS. При написании статьи я ориентировался именно на аналитиков, потому что чаще всего допиливание, валидация и публикация API для конечного потребителя — это наша ответственность. Ниже постарался осветить вариант решения задачи унификации и автоматизации процесса разработки API в крупном банке.

Для чего нужна система управления проектированием API?

Цифровая экосистема любой крупной организации сегодня состоит из большого количества разных информационных систем, а у этих систем есть множество пользователей, причем как внутри организации, так и за ее пределами. Современные информационные системы построены по принципу веб-сервера, с фронтом и бэком, которые общаются между собой при помощи API (Application Programming Interface) — определенного набор правил, инструкций, методов, структур данных и некоторых проверок, которые позволяют информационным системам обмениваться данными друг с другом.

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

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

Таким образом, назначение системы управления проектированием API банка можно сформулировать так:

1. Обеспечение взаимодействия банковских систем между собой.

2. Обеспечение требований информационной безопасности при межсистемном взаимодействии (в финтехе этот пункт по понятным причинам особенно актуален).

3. Унификация процесса публикации API информационных систем банка.

4. Единая точка администрирования API.

5. Сбор аналитики и агрегация статистики по использованию API.

Процессы управления — от проектирования до публикации API

Процесс проектирования я представил в виде статусной модели. Как видно, она разбита на три блока по назначению компонентов — управление архитектурой, реестр API и управление API:

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

Реестр API — это то самое место, с которым уже работают поставщики API, где происходят, собственно, проектирование интерфейса и его настройка. На основании данных, полученных из файла с выгрузкой, в реестре создается новая спецификация, то есть сущность, в которой в дальнейшем мы и будем настраивать API. В созданной спецификации поставщик осуществляет проектирование в формате OpenAPI. Разрабатывать API можно как в самом реестре, так и подготовить его заранее через Swagger в формате YAML, загрузить в файл спецификации и провалидировать его.

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

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

Управление API — это несколько систем, которые распределены по контурам: стенд интеграционно-функционального тестирования, предпрод для проведения приемо-сдаточных испытаний и продуктивная среда. Это три отдельные системы, в которые можно загружать сформированные спецификации.

Теперь рассмотрим ключевые этапы процесса в деталях.

Создание интерфейса системы

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

По центру — файлы с интерфейсами API. Их имя содержит код (1234) и мнемокод системы, указание на UI, синхронность (s), REST-взаимодействие, а также версию (v1). Слева отображена связь с платформой, которая обслуживает эту систему, а справа — с микросервисами, которые реализуют API. Если все клиенты и их системы известны на этапе проектирования, их также можно добавить, чтобы после выгрузки в реестр API можно было сразу настраивать их взаимодействие. В противном случае при появлении нового клиента нам придется возвращаться к этой схеме, вносить в нее изменения и обновлять API.

Платформа внутренних API

Комплекс средств обслуживания разработанных API называют «платформой внутренних API».

Какие функции она выполняет:

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

Tyk API Gateway

В качестве платформы внутренних API в банке используется система Tyk API Gateway. Эта система обеспечивает:

проксирование трафика;
контроль доступа к API;
преобразование данных внутри настроенных API;
ведение журналов использования;
контроль параметров авторизации;
логирование на уровне шлюза;
маскирование данных.

Tyk API Middleware

Все перечисленные выше задачи осуществляются с использованием middleware, или плагинов, которые позволяют:

прерывать при необходимости выполнение запросов;
модифицировать запросы и ответы;
валидировать запросы и ответы;
проводить размен токенов;
настраивать CORS и вызов внешних сервисов.

Обогащение API

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

К обогащению относятся:

настройка шлюза и контура публикации;
формирование базового пути;
настройка типа аутентификации;
настройка middleware, или плагинов;
маскирование данных;
настройка нефункциональных требований.

Расскажу обо всех пунктах подробно.

Выбор шлюза и контура публикации = типы API:

публичные: для взаимодействия двух информационных систем в контуре банка.
фронтальные: для взаимодействия фронта и бэка приложения.
файловые: для отправки/получения файлов.
внешние: для безопасного взаимодействия с системами банка внешних информационных систем за его контурами либо пользователей, живущих за пределами страны. Защищенные API в таком случае размещаются в специальном DMZ-контуре.

Формирование базового пути

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

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

/ui-api-web/name/service/v1

Настройка middleware, или плагинов

Плагины в системе управления API бывают двух видов:

Плагины вендора.

Идут вместе с поставкой Tyk API Gateway «из коробки». Это классические модификации запросов и ответов (как тела, так и заголовков) и их валидация на соответствие стандарту OpenAPI.

Собственные разработки.

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

расширенная валидация запросов и ответов по внутренним правилам — например, ограничение на размер тех или иных типов данных;
настройка интеграции с другими системами — например, с антивирусом или системой хранения контента;
файловые проверки: помимо классической антивирусной проверки, в банках к файловому обмену предъявляются дополнительные требования, поэтому файловые API выделены в отдельный шлюз;
размен токенов;
проверка anti-replay.

Валидация также бывает двух видов:

Автоматическая валидация при разработке внутри реестра API:

валидация нотацией OpenAPI;
валидация заполнения обязательных параметров;
валидация по настроенным правилам.

Настраиваемая валидация запросов и ответов на соответствие логической схеме — дополнительные плагины, которые позволяют включить валидацию при взаимодействии клиента с API. При включении такой валидации она также будет проходить автоматически. В случае поступления данных, которые не соответствуют описанной структуре данных, система просто вернет ошибку 422.

Интеграции — настройка параметров, необходимых для вызова другой системы:

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

Маскирование

В финтехе мы неизбежно взаимодействуем с конфиденциальной информацией — банковской тайной и персональными данными пользователей, защищаемых соответствующим Федеральным законом № 152. По требованиям информационной безопасности, принятым и утвержденным архитектурным комитетом, эти данные необходимо маскировать при передаче с помощью настройки параметров заголовков и тел методов. Настроенные параметры не отображаются в вызовах методов и журнале событий системы управления API — вместо них мы видим «*».

Проверка корректности маскирования всегда включается в протокол тестирования — без нее релиз не пройдет приемо-сдаточные испытания.

Файловые проверки

Настройка на уровне плагинов параметров проверок при загрузке и выгрузке файлов:

ограничения размера файлов;
перечень разрешенных расширений;
дополнительные параметры и адреса сервисов.

Нефункциональные требования

Чтобы канал не забивался при подключении, для каждого клиента API выставляются требования к пропускной способности, ограничения на размер пакета и таймауты.

Пример обогащения API

Вот как выглядит обогащение API внутри YAML-файла:

Выгрузка спецификации API

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

Импорт спецификации API

Как я уже говорил, импорт спецификации происходит в третьей системе — системе управления API. У каждого контура она своя.

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

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

Использование API

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

Выводы

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

К сожалению, у системы есть и свои недостатки:

Сложный процесс (вы наверняка заметили это по длине статьи). В случае серьезных изменений (например, добавления нового поставщика) весь процесс придется пройти по новой. Ошибившись на одном из этапов, можно случайно сломать все, что было до этого.
Отсутствие мониторинга выгрузки интерфейсов в Реестр API. Если по расписанию не произошла выгрузка спецификации, придется идти и разбираться вручную.
Смена правил валидации API или настройке в реестре API без уведомлений пользователей. Бывает, что ты спокойно разрабатываешь API, а на следующий день приходишь в тот же самый реестр, а у него обновилась сборка, и уже все настройки находятся в другом месте. Никаких пояснений к релизу при этом нет.
Отсутствие развернутого протокола импорта спецификаций API. Если при загрузке спецификации возникает ошибка, то также приходится вручную разбираться, что пошло не так.

И тем не менее при работе на крупном финтех-проекте плюсы использования соответствующей системы сильно перевешивают минусы!

ссылка на оригинал статьи https://habr.com/ru/articles/889832/