В данной публикации будут затронуты следующие темы:

• Когда появляется необходимость применять версионирование
• Как правильно обозначать версии своего кода
• Какие популярные типы API-версионирования применяются на практике
• Практика. Добавляем версионирование для нового проекта ASP.NET Core WebAPI
• Практика. Добавляем версионирование для OpenAPI
• Практика. Добавляем версионирование для Swagger
• Всегда ли стоит применять версионирование? Проблемы и минусы

Что такое версионирование кода

В разработке программного обеспечения версионирование кода продукта означает назначение уникального номера версии каждому релизу. Это обычная практика при создании ПО, поскольку она позволяет разработчикам и пользователям отслеживать каждую новую версию продукта. Однако применение этой концепции к веб-приложениям имеет свои особенности, поскольку приложения обычно публикуются в одном статическом URI (имя хоста, домен или папка), и любая новая версия переопределяет предыдущую.

Что такое версионирование кода

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

Добавление системы версионирования в наш код и ее применение к нашим API может снизить риск нарушения работы всех участников процесса. Вместо того чтобы накатывать обновления непосредственно к действующему API, заставляя всех клиентов использовать его немедленно, мы можем опубликовать новую версию в новом месте, доступном с помощью различных методов (таких как URL-сегменты или HTTP-заголовки), не удаляя и не заменяя старые версии. В результате последняя версия и старая версия находятся в сети одновременно, что дает клиентам возможность немедленно переключиться на новую версию или придерживаться предыдущей, пока они не будут готовы принять изменения.

Версионирование кода позволяет нашему API развиваться плавно и поэтапно, независимо от клиентов, использующих его.

Когда появляется необходимость применять версионирование кода

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

Какие изменения в коде API можно считать критическими? Вот неполный список, вы можете отнести сюда и любые свои, актуальные для вашего API или бизнес-логики:

• Добавление новых, переименование или удаление существующих endpoints или их параметров
• Изменение логики исполнения существующих API
• Изменения типа ответа или кода ошибки существующих API
• Изменения в структуре DTO ответа

Таким образом, рано или поздно нам придется столкнуться с этими проблемами и внедрить в свой проект версионирование кода, поскольку это способ поддержания обратной совместимости нашего кода API.

Как правильно обозначать версии своего кода

Наиболее распространенной методологией версионирования является Семантическое версионирование.

Семантическое версионирование

Однако версионирование Web API немного отличается от классического версионирования ПО. Многие разработчики придерживаются соглашения, что PATCH-версия является недопустимой при нумерации версий, также иногда отказываются и от MINOR-версии в своих проектах (не всегда). Аргументы следующие: API-версия не то же самое что бинарная версия файла. API-версии должны быть дискретными натуральными числами. Более того, зачастую изменения в API являются внутренними на сервере и никак не затрагивают работу клиента этого API, а если клиент не знает об этих изменениях и не видит разницы, тогда зачем вообще присваивать для таких изменений в API новую версию?

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

Популярные типы API-версионирования

Наиболее распространенные подходы к версионированию кода следующие:

• URL versioning: https://site.com/api/v1/getdata
  Внутри строки URL добавляется специальный сегмент, который обозначает конкретную версию API.
• Query parameter versioning: https://site.com/api/getdata?api-version=1
  К строке запроса добавляется специальный параметр, значением которого является конкретная версия API.

Мы как раз реализуем в нашем проекте эти два подхода, указанные выше. Также существуют другие, менее распространенные подходы: через HTTP-заголовки, разные названия endpoints-методов для разных версий API.

Практика. Добавляем версионирование для нового проекта ASP.NET Core WebAPI

Для начала создадим новый проект типа ASP.NET Core Web API со стандартными настройками. Я использую для работы Visual Studio 2022, среда выполнения: .NET 9.0:

Тип проекта: ASP.NET Core Web API

Определим название и расположение нового проекта

Отметим галочками важные для нас настройки

* в преднастройках проекта укажем поддержку OpenAPI, поддержку контроллеров. Остальное по желанию.

Далее переключимся в файл Program.cs. Я удалил стандартные шаблонные комментарии и немного отрефакторил код. Перед началом работы код файла выглядит так:

namespace CodeVersioning
{
    public class Program
    {
        public static void Main(string[] args)
        {
            WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

            builder.Services.AddControllers();
            builder.Services.AddOpenApi();

            WebApplication app = builder.Build();

            if (app.Environment.IsDevelopment()) 
                app.MapOpenApi();

            app.UseHttpsRedirection();
            app.UseAuthorization();
            app.MapControllers();

            app.Run();
        }
    }
}

Далее нам нужно добавить в проект следующие NuGet-пакеты:

1. Microsoft.AspNetCore.OpenApi (добавлен изначально, т.к. выбран шаблон проекта ASP.NET Core Web API)
2. Asp.Versioning.Http
3. Asp.Versioning.Mvc
4. Asp.Versioning.Mvc.ApiExplorer

Добавляем необходимые NuGet-пакеты

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

После этого нужно подключить новые сервисы в файле Program.cs. Сделаем это прямо после команды builder.Services.AddOpenApi(); после строчки код №10 из листинга выше:

//Добавляем поддержку версионирования
builder.Services.AddApiVersioning(options =>
    {
        //Версия API по умолчанию
        options.DefaultApiVersion = new ApiVersion(1);
        //Добавляем специальные HTTP-заголовки, в которых перечислены актуальные и устаревшие версии API
        options.ReportApiVersions = true;
        //Используем версию API по умолчанию, если клиент явно не указал нужную ему
        options.AssumeDefaultVersionWhenUnspecified = true;
        //Определяем, что будем ожидать нужную версию API в самой строке запроса или в URL-сегменте
        options.ApiVersionReader = ApiVersionReader.Combine(
            new UrlSegmentApiVersionReader(), //site.com/v2/getdata
            new QueryStringApiVersionReader("version")); //site.com/getdata?version=2
    })
    //Подключаем поддержку MVC для версионирования API
    .AddMvc()
    //Данный метод исправляет конечные маршруты и подставляет нужную версию API через параметр в маршруте.
    .AddApiExplorer(options =>
    {
        options.GroupNameFormat = "'v'V";
        options.SubstituteApiVersionInUrl = true;
    });

Как видно из кода выше, мы хотим реализовать для наглядности сразу два подхода: через URL-сегменты /vX/ и через специальный параметр version в строке запроса. Также отдельно рассмотрим версионирование т.н. minimal API.

Этап 1. Версионирование через параметр в строке запроса

Начнем со второго варианта. Для этого в папке Controllers создадим новый API-controller с названием QueryStringController.cs (существующий по умолчанию WeatherForecastController.cs пока что трогать не будем, оставим его для реализации второго подхода). Идея будет в следующем. У нас есть список предустановленных вместе с шаблоном характеристик для погоды:

private static readonly string[] Summaries = [
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
];

Этот список всех описаний погоды мы будем отдавать клиенту. Версия 1 нашего API будет отдавать только названия, начинающиеся с буквы "B", версия 2 - начинающиеся с буквы "С", версия 3 - начинающиеся с буквы "S":

using Asp.Versioning;
using Microsoft.AspNetCore.Mvc;

namespace CodeVersioning.Controllers
{
    //С помощью атрибутов настраиваем контроллер для работы с API,
    //также перечисляем, какие версии API поддерживаются
    [ApiController]
    [ApiVersion(1)]
    [ApiVersion(2)]
    [ApiVersion(3)]
    //Добавляем в маршрут приписку "api/" для выразительности
    [Route("api/[controller]")]
    public class QueryStringController : ControllerBase
    {
        //Список погодных состояний
        private static readonly string[] Summaries = [
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        ];

        //Обязательно указываем, через какой HTTP-метод клиент может обратиться к API
        [HttpGet]
        //Программируем три разные модификации метода Get(), через специальный атрибут MapToApiVersion
        //разделяем к ним доступ по соответствующим версиям WebApi
        [MapToApiVersion(1)]
        public IEnumerable<string> Get1()
        {
            return Summaries.Where(x => x.StartsWith("B"));
        }

        [HttpGet]
        [MapToApiVersion(2)]
        public IEnumerable<string> Get2()
        {
            return Summaries.Where(x => x.StartsWith("C"));
        }

        [HttpGet]
        [MapToApiVersion(3)]
        public IEnumerable<string> Get3()
        {
            return Summaries.Where(x => x.StartsWith("S"));
        }
    }
}

Соберем проект и запустим его на выполнение. Проверим, как работает версионирование нашего API через специальный параметр в строке запроса.

Если при создании нового проекта вы отметили галочкой опцию на использование HTTPS-соединения, то возможно Visual Studio спросит у вас разрешения доверять выпущенному SSL-сертификату. Соглашаемся и нажимаем "Да / Yes":

Я доверяю SSL-сертификату

Я доверяю SSL-сертификату

Если просто обратиться по соответствующему маршруту без явного указания версии API, то по умолчанию отработает версия 1, т.к. мы явно прописали это при настройке сервисов в файле Program.cs.

https://localhost:44377/api/querystring

Через специальный параметр version можно указать нужную версию API следующим образом:

https://localhost:44377/api/querystring?version=3

Теперь давайте представим, что наш WebApi успешно развивается, и в процессе своего жизненного цикла версия 1 признана устаревшей, и актуальной по умолчанию теперь является версия 2. Это можно легко запрограммировать:

//Версия API по умолчанию
options.DefaultApiVersion = new ApiVersion(2);
//Добавляем специальные HTTP-заголовки, в которых перечислены актуальные и устаревшие версии API
options.ReportApiVersions = true;

[ApiController]
[ApiVersion(1, Deprecated = true)] //версия 1 устарела
[ApiVersion(2)]
[ApiVersion(3)]
//Добавляем в маршрут приписку "api/" для выразительности
[Route("api/[controller]")]
public class QueryStringController : ControllerBase
{
//другой код

Если теперь мы обратимся к этому же endpoint без явного указания версии API через параметр version в строке запроса, то отработает метод Get2(), и мы увидим состояния погоды, начинающиеся с буквы "C". Помимо этого, в HTTP-заголовках ответа сервера будут перечислены актуальные и устаревшие версии API:

Версия API 1 устарела

Этап 2. Версионирование через URL-сегменты

Далее реализуем версионирование кода еще одним способом - через URL-сегменты. Этот способ во многом отличается от первого способа. Теперь для обращения к разным версиям API мы вынуждены использовать разные URL. Например, https://site.com/v1/getdata или https://site.com/v3/getdata.

За основу возьмем созданный по умолчанию контроллер WeatherForecastController.cs и класс-модель WeatherForecast.cs, который находится в корне нашего проекта.

Идея будет в том, что в разных версиях API мы по-разному будем отдавать информацию о погоде. А именно, для новой версии нашего WebAPI мы создадим новый класс-модель на базе существующего, он будет немного отличаться для наглядности. Определим эти классы в соответствующие директории. Также переименуем контроллер на UrlSegmentController.cs. Теперь файловая структура проекта выглядит так:

Файловая структура проекта выглядит так

Исходный класс WeatherForecast.cs в папке V1 оставим без изменений, а производный от него немного изменим:

namespace CodeVersioning.Models.V2
{
    public class WeatherForecast
    {
        public DateOnly Date { get; set; }

        public string? Summary { get; set; }

        public Guid YourApiKey { get; set; }
    }
}

Теперь напишем логику внутри контроллера UrlSegmentController.cs:

using Asp.Versioning;
using Microsoft.AspNetCore.Mvc;

namespace CodeVersioning.Controllers
{
    //С помощью атрибутов настраиваем контроллер для работы с API,
    //также перечисляем, какие версии API поддерживаются
    [ApiController]
    [ApiVersion(1, Deprecated = true)]
    [ApiVersion(2)]
    //Добавляем в маршрут приписку "api/" для выразительности.
    //Также добавляем служебный сегмент "vX/ для указания целевой версии API
    [Route("api/v{version:apiVersion}/[controller]")]
    public class UrlSegmentController : ControllerBase
    {
        //Список погодных состояний
        private static readonly string[] Summaries = [
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        ];

        //Обязательно указываем, через какой HTTP-метод клиент может обратиться к API
        [HttpGet]
        //Программируем две разные модификации метода Get(), через специальный атрибут MapToApiVersion
        //разделяем к ним доступ по соответствующим версиям WebApi
        [MapToApiVersion(1)]
        public IEnumerable<Models.V1.WeatherForecast> Get()
        {
            //Функционал первой версии метода Get() оставляем без изменений
            return Enumerable.Range(1, 5).Select(index => new Models.V1.WeatherForecast
            {
                Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            });
        }

        [HttpGet]
        [MapToApiVersion(2)]
        //Через новый параметр "range" можно вручную указать кол-во записей в ответе
        public IEnumerable<Models.V2.WeatherForecast> GetV2(int? range)
        {
            //Для версии API 2: используем другую версию модели WeatherForecast
            return Enumerable.Range(1, range ?? 5).Select(index => new Models.V2.WeatherForecast
            {
                Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)],
                YourApiKey = Guid.NewGuid()
            });
        }
    }
}

Соберем проект и запустим его на выполнение. Для данного контроллера у нас есть две опции, две версии нашего API. Например, обратимся к версии 2, при этом через параметр range укажем количество записей в ответе (2 записи):

https://localhost:44377/api/v2/urlsegment?range=2

Этап 3. Версионирование для Minimal APIs

Основная идея Minimal APIs заключается в том, что для реализации работы WebAPI задействуется минимум из всего доступного функционала фреймворка ASP.NET Core. Например, для определения конкретных endpoints не используется функционал контроллеров, вместо этого применяются лямбда-выражения и т.д.

Переключаемся в файл Program.cs и в самом низу перед командой app.Run(); напишем следующий код:

//Определяем общий ApiVersionSet для всех endpoints.
//В этом примере для Minimal APIs реализуется две версии API
ApiVersionSet apiVersionSet = app.NewApiVersionSet()
    .HasDeprecatedApiVersion(new ApiVersion(1))
    .HasApiVersion(new ApiVersion(2))
    .ReportApiVersions()
    .Build();

//Один endpoint, но разный функционал, в зависимости от версии API
app.MapGet("api/getdata", () => Results.Text("v1"))
    .WithApiVersionSet(apiVersionSet)
    .MapToApiVersion(new ApiVersion(1));
app.MapGet("api/getdata", () => Results.Text("v2"))
    .WithApiVersionSet(apiVersionSet)
    .MapToApiVersion(new ApiVersion(2));

app.Run();

Еще раз собираем проект, запускаем и пробуем обратиться по новому адресу нашего API:

https://localhost:44377/api/getdata?version=1

Практика. Добавляем версионирование для OpenAPI

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

Рассмотрим пример со всеми настройками по умолчанию. Здесь все предельно просто. Visual Studio уже заранее подключила функционал OpenAPI за нас. Чтобы убедиться в этом, в файле Program.cs найдем строчку кода:

builder.Services.AddOpenApi();

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

//Определяем три разных версии документа спецификации
builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");
builder.Services.AddOpenApi("v3");

После этого, предварительно собрав проект, мы можем обратиться к разным версиям документа OpenAPI. Например, обратимся к документу v2.json, по стандартному URL для OpenAPI в проекте:

https://localhost:44377/openapi/v2.json

Анализируя структуру полученного документа, можно удостовериться, к примеру, что в версии 2 нашего WebAPI появился входной параметр range, класс-модель WeatherForecast.cs также немного отличается от исходного (а для версии 3 он и вовсе будет не определен).

Практика. Добавляем версионирование для Swagger

Добавим в наш проект Swagger, а также настроим его так, чтобы данный инструмент смог описать все версии нашего WebAPI.

Для начала подключим необходимые NuGet-пакеты:

1. Swashbuckle.AspNetCore.Swagger
2. Swashbuckle.AspNetCore.SwaggerGen
3. Swashbuckle.AspNetCore.SwaggerUI

Подключим необходимые NuGet-пакеты

Таким образом, всего в нашем проекте подключено семь Top-level пакетов.

Далее переключаемся в файл Program.cs и добавляем поддержку Swagger сразу же после кода настройки OpenAPI:

//Добавляем поддержку Swagger
builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo() { Title = "CodeVersioning", Version = "v1" });
    options.SwaggerDoc("v2", new OpenApiInfo() { Title = "CodeVersioning", Version = "v2" });
    options.SwaggerDoc("v3", new OpenApiInfo() { Title = "CodeVersioning", Version = "v3" });
});

Далее опускаемся ниже, находим блок с условной конструкцией if(app.Environment.IsDevelopment()) {}. Там уже определена настройка для OpenAPI. Дописываем необходимый код для Swagger:

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "CodeVersioning v1");
        options.SwaggerEndpoint("/swagger/v2/swagger.json", "CodeVersioning v2");
        options.SwaggerEndpoint("/swagger/v3/swagger.json", "CodeVersioning v3");
    });
}

Все готово. Соберем проект, запустим его на выполнение и обратимся по стандартному адресу для доступа к Swagger:

https://localhost:44377/swagger/index.html

Swagger предоставляет удобный HTML-интерфейс для ознакомления с нашим API. Также на этой же странице можно протестировать работу различных endpoints. Для этого нужно развернуть требуемый блок и выполнить команды "Try it out => Execute":

Обзор функционала Swagger

Всегда ли стоит применять версионирование? Проблемы и минусы

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

• Увеличение сложности. Основная цель стратегии версионирования состоит в том, чтобы поддерживать несколько версий одного и того же API одновременно. Такая стратегия, скорее всего, приведет к значительному увеличению числа доступных endpoints, что в свою очередь подразумевает необходимость работы с большим объемом дополнительного исходного кода.
• Конфликт с принципом DRY. Принцип «Не повторяй себя» (Don’t Repeat Yourself, DRY). Если мы хотим следовать этому принципу, то должны иметь одну, четкую и авторитетную реализацию для каждого компонента кода. Однако версионирование API часто приводит к противоположному результату, известному как «Пиши всё дважды» или «Пиши каждый раз заново» (Write Everything Twice или Write Every Time, WET).
• Проблемы безопасности и стабильности. Добавление новых функций - это не единственная причина для обновления WebAPI. Иногда мы вынуждены обновлять API для исправления ошибок, улучшения производительности, устранения уязвимостей безопасности, которые могут негативно повлиять на систему, или для внедрения новых стандартов, известных своей стабильностью и безопасностью. Если при этом мы оставляем старые версии API доступными, то оставляем «открытую дверь» для таких проблем. В худшем случае злоумышленник может использовать наш WebAPI, эксплуатируя уязвимость, которую мы исправили несколько лет назад, но которая всё ещё доступна в уязвимой endpoint.
• Неправильный образ мышления. Этот недостаток менее очевиден, чем предыдущие, но не менее важен. Опора на версионирование API может повлиять на то, как мы думаем о развитии нашего приложения. Мы можем быть склонны к рефакторингу системы таким образом, чтобы она оставалась обратимо совместимой, чтобы старые версии API могли по-прежнему её использовать. Такой подход может затронуть не только исходный код, но и другие архитектурные слои проекта: схемы базы данных, шаблоны проектирования, бизнес-логику, стратегии извлечения данных, структуру DTO и так далее. Мы можем отказаться от внедрения новой версии сторонней библиотеки, потому что её интерфейс будет несовместим со старой версией нашего API, которую мы продолжаем поддерживать, потому что некоторые клиенты всё ещё активно её используют - а делают они это, потому что мы им это позволяем.

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

Вместо заключения (забавное наблюдение)

Большинство из вышеописанных и других недостатков были упомянуты Роем Филдингом в нескольких публичных выступлениях. В августе 2013 года, во время выступления на конференции Adobe Evolve, он дал совет о том, как подходить к версионированию API в RESTful веб-сервисах, выразив это одним словом: «не надо».

Слайд из презентации Роя Филдинга