При разработке программных решений встает задача управления изменениями ваших публичных API во времени. Например, у вас есть 2 сервиса А и Б. Сервис А делает запросы к сервису Б по REST API для получения необходимой информации. А зависит от Б, так как для его работы необходима информация из Б. Мы выпускаем новую версию сервиса Б, в которой изменилось API. Как сообщить клиентам сервиса Б, совместим ли API с предыдущей версией?
В системах с множественными зависимостями выпуск новой версии сервиса может превратиться в кошмар. Выпуск новой версии сервиса может быть заблокирован тем, что будет необходимо также обновить все зависимые сервисы.
Для решения вышеописанных проблем можно воспользоваться Семантическим версионированием (Semantic Versioning) - набором правил и требований, которые определяют, как назначаются и увеличиваются номера версии.
Основная идея
В семантическом версионировании рассматривается формат версий X.Y.Z (мажорная, минорная, патч). Баг-фиксы, не влияющие на API, увеличивают патч-версию, обратно совместимые добавления/изменения API увеличивают минорную версию и обратно несовместимые изменения API увеличивают мажорную версию.
По ссылке выше сформулирована спецификация именования версий, которая на данный момент состоит из 11 пунктов. Подробнее со спецификацией можно ознакомится на странице.
Зачем это использовать
Это не новая или революционная идея. Вероятно, вы уже используете что-то подобное. Проблема в том, что «подобное» — не достаточно хорошо. Без соответствия формальной спецификации, номера версий практически бесполезны для управления зависимостями. Ясно определив и сформулировав идею версионирования, становится легче сообщать о намерениях пользователям вашего ПО. Когда эти намерения ясны, гибки (но не слишком), спецификации зависимостей наконец могут быть созданы.
Примеры
На практике номер версии программного решения, который вы разрабатываете, может являться неким маркетинговым инструментом и может изменяться по своим уже устоявшимся правилам, и даже может вам, как разработчику, не принадлежать. Важно понимать, что номер версии программного решения может не равняться номеру версии публичного API данного приложения. Увеличение номера версии приложения может не увеличивать номер версии публичного API. И вы, как разработчик, можете ввести версионирование вашего публичного API.
Например, внутри вашего решения есть REST API. Вы можете использовать semver для его версионирования. Сообщать версии API можно через http заголовок accept в каждом ответе вашего API:
{
"accept": "application/myservice_api-0.5.1+json",
"date": "Mon, 05 Feb 2018 02:12:05 GMT",
"transfer-encoding": "chunked",
"content-type": "application/json;charset=UTF-8"
}
Все клиенты могут проверять accept заголовок ответов вашего API и "понимать" могут ли они работать с API данной версии или нет.
Ссылки
https://semver.org/ - страница со спецификацией семантического версионирования.
