run-dev

,

Версионирование API в C# ASP .NET Core

При разработке веб-API со временем могут появляться новые возможности, изменяться существующие или удаляться устаревшие функции. Чтобы клиенты API могли продолжать работу без сбоев, используется версионирование API.

Основные стратегии версионирования API

Версионирование через URL

Один из самых простых способов — указывать версию API в URL:

GET https://api.example.com/v1/products
GET https://api.example.com/v2/products

Этот метод понятен и удобен, но приводит к созданию множества URL-адресов.

Версионирование через заголовки

В этом методе версия API передается в заголовках HTTP-запроса:

GET /products
Accept: application/vnd.example.v1+json

Этот подход позволяет сохранить чистоту URL, но требует от клиентов явной передачи заголовка.

Версионирование через параметр запроса

Версию API можно передавать в качестве параметра запроса:

GET /products?version=1

Этот метод удобен, но может усложнять кеширование ответов.

Версионирование через медиатип

Использует Accept-заголовок с медиатипом, содержащим версию:

Accept: application/vnd.example+json;version=2

Реализация версионирования API в ASP.NET Core

В ASP.NET Core для версионирования API можно использовать пакет Microsoft.AspNetCore.Mvc.Versioning:

using Microsoft.AspNetCore.Mvc;

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/products")]
[ApiController]
public class ProductsController : ControllerBase
{
    [HttpGet]
    public IActionResult GetV1() => Ok(new { Message = "API v1" });
}

Также можно настроить версионирование через заголовки:

services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ApiVersionReader = new HeaderApiVersionReader("X-API-Version");
});

Клиент может указывать версию в заголовке:

GET /products
X-API-Version: 1.0

Лучшие практики версионирования API

  • Использовать явное указание версии, чтобы избежать неожиданных изменений.
  • Поддерживать несколько версий API, но ограничивать количество старых версий.
  • Сообщать клиентам о планируемом устаревании версий.
  • Автоматизировать тестирование API для разных версий.

Грамотное версионирование помогает обеспечивать стабильность API и облегчает его развитие без нарушения работы клиентов.

Больше записей