Когда в API надо поднимать версию?

Вот такой вопрос недавно задали моей знакомой на собеседовании.

На мой взгляд, тут нужно уточнить, какую версию собрались поднимать: major, minor, patch.

Major версию поднимают (v1-v2), когда изменения ломают обратную совместимость; в процессе меняется контракт, и клиентам нужно адаптироваться. Появился новый формат ответа API или обязательные поля, изменён протокол аутентификации или безопасности, переименован endpoint.

Minor версию поднимают (v1.2-v1.3) – если добавлено что-то новое, но совместимое, например, введены новые опциональные параметры.

Patch версию поднимают (v1.2.1 – v1.2.2) – когда исправляют баги, не меняющие контракт API.

Чаще всего речь, конечно, о версии major. Давайте посмотрим пример на основе системы быстрых платежей (СБП). Открытая документация находится тут -https://sbp.nspk.ru/api/

Кратко расскажу про СБП.

Это всеми известный способ оплаты, который осуществляется с помощью национальной системы платежных карт (НСПК). В данной системе регистрируются юридические лица (юр. л.), которые хотят получать оплату по СБП; им присваивается legalid. У юр. лиц есть точки продаж (это там, где вы, например, на кассе оплачиваете по СБП); каждой точке присваивается merchantid. Но для этого точке нужно зарегистрировать ТСП.

По ссылке https://sbp.nspk.ru/api/ найдете метод:
Post /merchant/v1/merchant/ и Post /merchant/v2/merchant.

В первой версии метода 11 параметров в запросе (адрес торговой точки, id банка, который регистрирует точку, id юр. лица, которому принадлежит точка).

Во второй версии 12 параметров: добавился “salesMode” - обязательный параметр, способ торговли ТСП. “salesMode” может принимать значения "REMOTE" и "FACE_TO_FACE". То есть торговая точка принимает оплату в реале, например, на кассе в Пятерочке или в онлайн-магазине. Рискну предположить, что впоследствии параметр будет активно использоваться фискальными органами, которые будут контролировать оплаты по СБП.

В данном случае добавление нового обязательного параметра при регистрации ТСП привело к поднятию версии.

Вот так просто.
Поднимали версии? Какие? Major❤️, Minor👍, Patch😜.