.NET Разработчик on Telegram: “День 1758. #ЗаметкиНаПолях Версионирование API.…”

День 1758. #ЗаметкиНаПолях
Версионирование API. Окончание
Начало

3. По HTTP-заголовку
Информация о версии отправляется в виде пользовательского заголовка в HTTP-запросе (X-API-Version: 1).
+ URL остаётся неизменным для разных версий, что может быть полезно для SEO и кэширования.
- Версию труднее обнаружить и сложнее тестировать, поскольку требуется установка HTTP-заголовков.

public class ProductsController : ApiController
{
  private const string HeaderName = "X-API-Version";

  [HttpGet]
  public IHttpActionResult Get()
  {
    var version = HttpContext.Current
      .Request.Headers[HeaderName];
    
    if (version == "1.0")
    {
      // Реализация для версии 1
      return Ok(…);
    }
    if (version == "2.0")
    {
      // Реализация для версии 2
      return Ok(…);
    }

    return BadRequest("Требуется версия API");
  }
}

4. По Media Type (заголовок Accept)
Информация о версии включается в заголовок Accept HTTP-запроса, часто с использованием пользовательского типа (application/vnd.myapi.v1+json).
+ Метод точно соответствует спецификации HTTP.
- Более сложно, а некоторым клиентам API может быть сложно управлять версиями.

[Produces("application/json")]
public class ProductsController : ApiController
{
  [HttpGet]
  public IHttpActionResult Get()
  {
    var version = GetVersionFromAcceptHeader();
    // реализация аналогична методу 3
  }

  private string GetVersionFromAcceptHeader()
  {
     var header = Request.Headers.
      Accept.FirstOrDefault();
     if (header != null)
     {
       var version = 
        header.Parameters.FirstOrDefault(
          p => p.Name.Equals("version",
           StringComparison.OrdinalIgnoreCase));
        return version?.Value;
     }
     return null;
  }
}

5. По имени хоста
Разные версии API размещаются на разных доменных именах (api-v1.example.com). Может осуществляться через маршрутизацию или перезапись URL. Обычно не обрабатывается непосредственно в контроллере, а скорее в настройках IIS или обратного прокси.
+ Наиболее интуитивно понятен для конечных пользователей.
- Требует дополнительной настройки инфраструктуры и может усложнить управление сертификатами SSL.

Итого
У каждого метода есть свои компромиссы, и выбор того, какой из них использовать, будет зависеть от конкретных требований и ограничений проекта. Также можно комбинировать эти методы. Конечная цель в том, чтобы поддерживать надёжный контракт с потребителями API, обеспечивая при этом возможность дальнейшего развития и улучшения сервисов, предоставляемых через API.

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