День 1757. #ЗаметкиНаПолях
Версионирование API. Начало
Версионирование используется для управления изменениями в API при сохранении обратной совместимости для существующих клиентов. Это позволяет разработчикам внедрять новые функции, исправлять ошибки или вносить другие изменения в API, не влияя на функциональность существующих интеграций.

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

Начиная с .NET 5, есть 5 вариантов версионирования API.

1. По URI (Пути)
Версия включается непосредственно в URL (/api/v1/products).
+ Наиболее простой и понятный метод.
- Может привести к дублированию URL и потребует от клиентов изменять URL для доступа к различным версиям.

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV1Controller : ApiController
{
  public IHttpActionResult Get()
  {
    // Реализация для версии 1
  }
}

[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV2Controller : ApiController
{
  public IHttpActionResult Get()
  {
    // Реализация для версии 2
  }
}

2. По строке запроса
Версия указывается в качестве параметра запроса в URL (/api/products?version=1).
+ Позволяет легко перейти на новую версию.
- Может быть не так очевидно, как управление через путь, и пользователи могут не заметить параметра.

public class ProductsController : ApiController
{
  const string DefaultVersion = "1.0";

  [HttpGet]
  public IHttpActionResult Get()
  {
    var version = HttpContext.Current
      .Request.QueryString["version"] 
     ?? DefaultVersion;
    
    if (version == "1.0")
    {
      // Реализация для версии 1
      return Ok(…);
    }
    if (version == "2.0")
    {
      // Реализация для версии 2
      return Ok(…);
    }
    
    return BadRequest("Версия не поддерживается");
  }
}

Окончание следует…

Источник: https://stefandjokic.tech/blog