Правила наименования сервисов и их интерфейсов (API)

1.

Title
Unit of measure
Правила наименования
сервисов и их
интерфейсов (API)
Материалы для рассмотрения
РГ по архитектуре при БИТ
Область влияния:
Весь Банк
Управление прикладной архитектуры
Департамента ИТ архитектуры
Март 2024

2.

Предпосылки
Title
В 5 версии checklist
Platform правила раздела ИА.РА присутствовали
Unit ofVTB
measure
В 6 версии checklist VTB Platform правила раздела ИА.РА были вынесены в «процессные правила»
Нейминг API необходим. За время «работы» правил, показал необходимость и актуальность использования
для управления в части интеграционной архитектурой
Контроль правил был реализован в iServer, Реестре API
Перенос стандарта в «процессные правила» привел к потере точки размещения стандарта нейминга API
2

3.

Вынесенные правила нейминга API из раздела checklist VTB Platform ИА.РА
Правила наименования Сервисов:
ИдСистемы.ИмяСервиса
Title
Unit of measure
Где:
ИдСистемы - Идентификатор системы РИС или константа ext (для систем за периметром банка)
ИмяИнтерфейса - Имя сервиса, согласно рекомендациям ниже.
Рекомендации к наименованию имени Сервиса
Должно отражать суть функциональности, предоставляемой системой внешним потребителям.
Для сервисов Партнеров (внешних поставщиков сервисов) должно отражать, дополнительно, имя Партнера.
Примеры:
• 1111.Обработка рублевых платежей
• 2222.Расчет графика платежей
• EXT.МВД. Выгрузка по Недействительным паспортам
• EXT.Почта РФ. Получение постановления ГИБДД
Сервисы системы будут верифицироваться и согласовываться корпоративными архитекторами (текущий процесс в iServer).
Обязательно вносить описание Сервиса – краткое описание функциональности (что потребитель получит через этот Сервис).
3

4.

Вынесенные правила нейминга API из раздела checklist VTB Platform ИА.РА
Правила наименования API:
ИдСистемы.КодСистемы-ИмяИнтерфейса-ТипИнтеграции-МнемокодИнтеграции-Версия
Title
Unit of measure
Где:
ИдСистемы
- Идентификатор системы РИС или константа ext для внешних ИС (до реализации Реестра внешних ИС), или константа vtborg для систем Группы ВТБ. Допустим ввод только
идентификатора Системы, Ввод кода подсистемы запрещен).
КодСистемы - Идентификационный код системы РИС (для внутренних взаимодействий) или уникальный код внешней системы из iServer (буквенный идентификатор)
ИмяИнтерфейса - Имя интерфеса без метода, согласно рекомендациям ниже. Для продктового процессора должно начинатьсяc: pp_
ТипИнтеграции
s - синхронный
a - асинхронный
pub - публикация
sub - подписка
sa - синхронный поверх асинхронного
МнемокодИнтеграции
rest - REST
soap - SOAP
kafka - kafka
rabmq - rabbit mq
artmq - artemis mq
ibmmq - ibm mq
oauth - oauth
grpc - grpc
graphql - Graph QL
file - file
ws - Web Socket
Версия - мажорная версия, для новых, по умолчанию: v1
Примеры:
1442.cspc-person-s-rest-v1, ext.pcht-ordergibdd-s-file-v1
Рекомендации к наименованию имени интерфейса:
Имя интерфейса должно отражать объект (сущность), который предоставляется через интерфейс потребителям и выполняемое над ним действие.
пример:
RequestHistory, TransformPayment
В случае невозможности выделения выполняемого действия (через интерфейс выполняется множество действий и нельзя выделить что-то одно) - только объект, пример:
Credit, Deposit, Person
4

5.

ПРАВИЛА ИА.РА VTB PLATFORM CHECKLIST 5 ВЕРСИЯ
ID
Класс системы
Цель стандарта
Название документа
Стандарт
STICKER
Критичность
ТехДолга*****
Обяз-ть**
Дата начала
применения
ИА.РА.07
КП, Unit
СУБО,
Унификация
of measure
ОПС, ОС, СС,
наименования
ИС,
API
Библиотека
Наименование Сервисов в
Реестре API формируется по
правилам приложения 5.0
Раздел ИА.РA Реестр
API#НаименованиеАПИ
Medium
Must
18.10.2021
ИА.РА.08
КП, СУБО,
ОПС, ОС, СС,
ИС,
Библиотека
Наименование интерфейсов
(API) в Реестре API формируется
по правилам приложения 5.0
Раздел ИА.РA Реестр
API#НаименованиеАПИ для
всех видов взаимодействия
Medium
Must
18.10.2021
Унификация
наименования
API
5

6.

Предпосылки изменений
Необходимость описания интерфейсов внутри КП.
Пример (для Android): Title
package ru.vtb.subopackage
Unit of measure
import ru.vtb.channelapppackage.AnalyticsManager
<...>
class SuboClass @Inject constructor(private val analyticsManager: AnalyticsManager) :
SuboBaseClass {
private fun sendEvent(event: AnalyticsEvent) {
analyticsManager.sendEvent(event)
}
}
Предложение добавить мнемокоды:
- csapk используется для описания интерфейсов, реализованных на платформе Android,
- csipa - используется для описания интерфейсов, реализованных для iOS,
- csjs - используется для описания интерфейсов, реализованных для веб-браузера.
- csipa, csapk, csjs применимы для систем классов СУБО/СУБО+/КП и используются для описания интеграции между фронтом ИС1 и фронтом ИС2 в случае,
когда ИС1 подключает в свой код зависимость от репозитория в зоне ответственности ИС2 и вызывает в коде ИС1 методы классов из репозиториев ИС2.
Распространённый случай: переиспользование функциональности КП во фронтах СУБО.
Необходимость выделения отдельного признака для продуктовых процессоров — для обеспечения возможности контроля
применения правил ШП.
6

7.

Изменения в правилах нейминга API
Правила наименования API:
ИдСистемы.КодСистемы-ИмяИнтерфейса-ТипИнтеграции-МнемокодИнтеграции-Версия
Где:
ИдСистемы
- Идентификатор системы РИС или константа ext (только нижний регистр) для внешних ИС (до реализации Реестра внешних ИС), или константа vtborg (только нижний
регистр) для систем Группы ВТБ. Допустим ввод только идентификатора Системы, Ввод кода подсистемы запрещен. Указывается идентификатор системыпоставщика API.
Title
Unit of measure
КодСистемы - Идентификационный код системы РИС (для внутренних взаимодействий) или уникальный код внешней системы из iServer (буквенный идентификатор). Только
нижний регистр. Допустим ввод только идентификатора Системы, Ввод кода подсистемы запрещен. Указывается идентификатор системы-поставщика API.
ИмяИнтерфейса - Имя интерфеса без метода, согласно рекомендациям ниже. Для продуктового процессора должно начинаться с: «pp_»
ТипИнтеграции
s - синхронный
a - асинхронный
pub — публикация (со стороны Поставщика API: Поставщик API публикует данные и нет ответа — не предполагается ответа от Потребителя API)
sub — подписка (со стороны Поставщика API: Поставщик API получает данные и нет ответа для Потребителя API — не предполагается ответа от Поставщика API)
sa - синхронный поверх асинхронного
МнемокодИнтеграции
rest — REST
soap — SOAP
kafka — kafka в периметре конкретной ИС
rabmq - rabbit mq
jdbc (нецелевой способ интеграции между системами)
COM (нецелевой способ интеграции)
smtp (нецелевой способ интеграции)
ibmmq - ibm mq (нецелевой способ интеграции)
grpc — grpc
file — file
сsapk - используется для описания интерфейсов, реализованных на платформе Android
csipa - используется для описания интерфейсов, реализованных на платформе для iOS
csjs - используется для описания интерфейсов, реализованных на платформе для веб-браузера
mrcp - протокол MRCP
odbc (нецелевой способ интеграции)
sonicmq (нецелевой способ интеграции)
artmq - artemis mq
oauth - oauth
graphql - Graph QL
ws - Web Socket
Версия - мажорная версия, для новых, по умолчанию: v1
7

8.

Рекомендации к наименованию интерфейса, в рамках стандарта нейминга API
Рекомендации к наименованию имени интерфейса:
Имя интерфейса должно отражать объект (сущность), который предоставляется через интерфейс потребителям и выполняемое над ним действие.
Title
Допустимо применение только одного символа: нижнее подчеркивание «_». Другие символы недопустимы.
Для продуктовых процессоров
Unit of обязательно
measure использование технического мнемокода «pp_».
Нижнее подчеркивание должно использоваться только для разделения сутевой части имени и технического мнемокода:
Технический мнемокод_имяИнтерфейса
Технический мнемокод применим для:
Продуктовых процессоров
Должен использоваться: «pp_»
Подсистем
Допустимо (опционально, при необходимости) использовать: «мнемокод подсистемы_» - мнемокод подсистемы из РИС!
Продуктовых процессоров, заявленных как подсистема
Должен использоваться сначала мнемокод продуктового процессора: «pp_мнемокод подсистемы_»
Если технический мнемокод отсутствует — нижнее подчеркивание не должно применяться.
Примеры:
RequestHistory, TransformPayment
pp_debitCard,
swh_rexts_crudlExtSystems: swh_rexts является мнемокодом подсистемы в РИС.
В случае невозможности выделения выполняемого действия (через интерфейс выполняется множество действий и нельзя выделить что-то одно) - только объект.
Примеры:
Credit, Deposit, Person
Правила наименования Интерфейсов вида GUI:
В названиях интерфейсов вида GUI рекомендуется так и писать "хххх.GUI моей системы" или "хххх.GUI пользовательский интерфейс" никаких мнемокодов для
GUI нет.
Где:
хххх — Идентификатор системы РИС или константа ext (только нижний регистр) для внешних ИС (до реализации Реестра внешних ИС), или константа vtborg
8
(только нижний регистр) для систем Группы ВТБ. Допустим ввод только идентификатора Системы, Ввод кода подсистемы запрещен.

9.

Примеры нейминга API
Примеры:
1442.cspc-person-s-rest-v1 — внутренняя API
Title
ext.pcht-ordergibdd-s-file-v1
— партнерская
API
Unit
of measure
1493.swh-swh_rexts_crudlAPI-s-rest-v1 — внутренняя API подсистемы
vtborg.anyw-payNow-a-kafka-v1 - партнерская API системы группы ВТБ
1446.dks-pp_dks_NTPrd_CRUDLCards-s-rest-v1 — API продуктового процессора, зарегистрированного в РИС в качестве подсистемы.
9

10.

Основные принципы для формирования префиксов базового пути (BasePath)
Правила формирования базового пути платформы: /ТипВзаимодействия/ТипДанных/Канал/ТипAPI/ГБЛ/КодСистемы/ИмяИнтерфейса/Версия/Глагол из словаря глаголов
где:
STICKER
ТипВзаимодействия — мнемокод типа взаимодействия:
Внешнее — outside
Внутреннее — inside
ТипДанных — мнемокод типа используемых в API данных:
Конфиденциальные — conf
Не конфиденциальные — public
Канал — канал или кп, или транспорт
Мобильное приложение — mb
Интернет/web-приложение — web
Любой (для всех каналов одинаково) — uni
Моноприложение (не встроен в КП) — ui
Устройство самообслуживания — atm
Приложение — app (для backend-to-backend)
Файловый транспорт — ft
Мнемокод КП — ibrb / pkb / frnt (мнемокод КП из РИС)
Мнемокод канала (из Реестра API) — vtbo (втб онлайн, который объединяет ibrb и mbrb)
ТипAPI — мнемокод типа API
Публичные — publicapi
Закрытые — intsecapi
Фронтальные — frontapi
Открытые — openapi
Партнерские — partnerapi
Кастомные — secapi
Внешние - extapi
ГБЛ — принадлежность API ГБЛ (владельца API)
РБ — rb
КИБ — kib
СМБ — smb
Не определен - cross , для общих сервисов (т.е. реализовываются для предоставления общей услуги и вне определенного ГБЛ)
Название документа
Unit of measure
КодСистемы - Идентификационный код системы (буквенный код из РИС, для ИС Банка, мнемокод для внешней ИС) поставщика API. Для внешних ИС — в начало добавляется префикс
«ext_» (разделение мнемокодоа ИС через нижнее подчеркивание. Пример: ext_yandex). Для систем группы ВТБ — в начало добавляется «vtborg_».
ИмяИнтерфейса - Имя интерфейса, без метода (см. нейминг API). Для Продуктового процессора — должно начинаться с «pp». Допустимо: использование lowcase, с нижним
подчеркиванием. Нижнее подчеркивание, как разделитель «_» допустимо использовать для обозначения продуктовых процессоров (pp) и подсистем.
Версия - номер мажорной версии
10
Глагол из справочника глаголов — допустимо задавать ТОЛЬКО для API Продуктовых процессоров (признак: ИмяИнтерфейса начинается с «рр») - согласно ШП.53. Опционально.

11.

Рекомендации по формированию путей на балансировщиках
Правила формирования пути для разделения вызовов платформ api, agw, fgw, epa:
где:
/ТипВладения/ТипТочкиИнтеграции
STICKER
ТипВладения — мнемокод типа владения точки интеграции:
kp — канальное приложение. Применяется для всех gwaas
Название
документа
sysb — система Банка (СУБО/ИС
и тп, кроме
КП). Применяется для всех gwaas
sopi — для всех общих платформ
Unit of measure
epa— для аутентификации
ТипТочкиИнтеграции — мнемокод типа точки интеграции (м.б. расширен):
agwa — gwaas artemis-artemis
agwk — gwaas kafka-kafka
agwum — сегмент публичных/закрытых API Платформы Внешних Асинхронных API (--асинхронные взаимодействия)
agwus — сегмент закрытых API Платформы Внешних Асинхронных API (отдельно выделенных под ГБЛ) (--асинхронные взаимодействия)
agww — gwaas WebSocket
agws — gwaas SSE
fgw — gwaas Filegateway
tykf — сегмент фронтальных API Платформы Внутренних API (--синхронные взаимодействия)
tykml — сегмент публичных/закрытых API Платформы Внутренних API (--синхронные взаимодействия). Контур LAN
tykmg — сегмент публичных/закрытых API Платформы Внутренних API (--синхронные взаимодействия). Контур Шлюзовой Зоны
tyksl — сегмент закрытых API Платформы Внутренних API (отдельно выделенных под ГБЛ) (--синхронные взаимодействия). Контур LAN
tyksg — сегмент закрытых API Платформы Внутренних API (отдельно выделенных под ГБЛ) (--синхронные взаимодействия). Контур Шлюзовой Зоны
apicfc — сегмент фронтальных API Платформы Внешних API (--синхронные взаимодействия). Конфиденциальные данные
apicfn — сегмент фронтальных API Платформы Внешних API (--синхронные взаимодействия). Не конфиденциальные данные
apicmc — сегмент публичных/закрытых API Платформы Внешних API (--синхронные взаимодействия). Конфиденциальные данные
apicmn — сегмент публичных/закрытых API Платформы Внешних API (--синхронные взаимодействия). Не конфиденциальные данные
apicsc — сегмент закрытых API Платформы Внешних API (отдельно выделенных под ГБЛ) (--синхронные взаимодействия). Конфиденциальные данные
apicsn — сегмент закрытых API Платформы Внешних API (отдельно выделенных под ГБЛ) (--синхронные взаимодействия). Не конфиденциальные данные
fospinc — для обращения в s3, при использовании 1666.ФОСП. Конфиденциальные данные
fospinn — для обращения в s3, при использовании 1666.ФОСП. Не конфиденциальные данные
nspk — для использования сегментов НСПК
sphere — для использования сегментов СФЕРА
epai — внутренняя ЕПА (в контуре LAN)
epae — внешняя ЕПА (в контуре DMZ)
openapi — сегмент открытых API
11

12.

ПРАВИЛО VTB PLATFORM CHECKLIST
STICKER
ID
ИА.ОП.24
Класс системы
Цель стандарта
Название документа
of measure
Все Unit
системы
Унификация
Банка
наименования
API
Стандарт
Критичность
ТехДолга*****
Обяз-ть**
Дата начала
применения
Наименование интерфейсов
(API) в Реестре API формируется
по правилам приложения
Стандарт Нейминга API для всех
видов взаимодействия
Medium
Must
01.04.2024
12

13.

Процесс перехода нейминга API
Влечет ли это решение необходимость переименования для уже разработанного?
Для продуктовых процессоров
Title – да, обязательно (их отпустить не можем).
Unit of measure
Для остальных API (не продуктовые
процессора) – все новые должны по актуализированным правилам, все старые – при появлении мажорной версии API –
переход (т.е. при мажорных изменениях обязателен переход).
13

14.

Проект Решения
1. Принять к сведению актуализированные правила нейминга API и сопутствующие рекомендации
(слайды 7-11).
2. Согласовать добавление, в раздел VTB PLATFORM checklist ИА.ОП, правило и ссылку на стандарт
нейминга API - слайд 12.

15.

16.

ПРИЛОЖЕНИЕ 2: ЛИСТ ИЗМЕНЕНИЙ В ХОДЕ ПОДГОТОВКИ МАТЕРИАЛОВ
РГА
№
1.
Дата изменения
19.03.2024
Причины изменения
Замечания Д.Вознесенского, А.Прутик,
Г.Саркисьян
Корректировки материалов
Слайд 2 - корректировка предпосылок.
Слайд 7,8 — корректировка описаний, дополнения и
разъяснения
Слайд 10 — корректировка для: Глагол из справочника
глаголов — допустимо задавать ТОЛЬКО для API Продуктовых
процессоров (признак: ИмяИнтерфейса начинается с «рр») - согласно
ШП.53. Опционально.
- уточнено опциональное использование только для
продуктовых процессоров.
Добавлен слайд 13 — процесс перехода на
измененные правила нейминга API.
2.
21.03.2024
Замечания М.Намм
Расширение списка мнемокодов Интеграции.
Корректировка текстов (поехал за границы области
видимости).
Добавление рекомендации про нейминг GUI (слайд
8).

17.

Title
Unit of measure
17

18.

Совместимые и несовместимые изменения
Обратно совместимые изменения:
Обратно несовместимые изменения:
1. Добавление необязательного поля в модельный класс
1. Добавление обязательного поля в модельный класс
запроса.
2. Добавление поля в модельный класс ответа.
3. Добавление значения перечислимого типа.
4. Изменения наименования значения перечислимого
типа, если значение передается по порядку их
следования.
5. Изменение порядка значений перечислимого типа,
если значение передаются по наименованию.
6. Добавление media type, используемого для запроса.
7. Добавление необязательного параметра запроса.
8. Добавление необязательного заголовка запроса.
9. Добавление заголовка ответа.
10. Добавление нового кода ответа HTTP.
запроса.
2. Изменение типа поля в модельном классе запроса или
ответа.
3. Удаление значения перечислимого типа.
4. Изменение наименование значения перечислимого типа,
если значение передаются по наименованию.
5. Изменение порядка значений перечислимого типа, если
значения передаются по порядку их следования.
6. Изменение media type запроса или ответа.
7. Изменения метода HTTP запроса.
8. Добавление обязательного параметра запроса.
9. Добавление обязательного заголовка запроса.
10. Изменение кода ответа HTTP.
11. Изменение URL эндпойнта.
Title
Unit of measure
18

19.

Версионирование: существующий сервис и API
Title
Unit of measure
19

20.

Версионирование: новый сервис и API
Title
Unit of measure
20

21.

Версионирование: изменение мажорной версии API
Title
Unit of measure
21