Версии API IMO должны быть на уровне API (примечание: под API я имею в виду набор ресурсов / маршрутов и их операций). Даже если вам нужно только увеличить версию одной конкретной операции для одного маршрута;все существующие операции API также должны быть доступны с использованием новой версии, например, у вас не должно быть сценария, когда одна операция доступна в /api/v2/template/thing, а вторая операция в том же API доступна только в /api/v1/template/item, а не /api/v2/template/item,Это может привести к путанице среди потребителей API.
Мы используем .NET Core в моей нынешней компании. Для достижения вышеизложенного классы контроллера API помечены атрибутами ApiVersion для всех известных версий. Определенные операции, которые не являются последней версией, помечены атрибутом MapToApiVersion - последние версии операций не помечены определенным MapToApiVersion например,
[ApiVersion("1.0")]
[ApiVersion("2.0")]
[ApiController]
[Route("api/v{version:apiVersion}/template/test")]
public class TestController : ControllerBase
{
[HttpGet]
[MapToApiVersion("1.0")]
public IActionResult Get()
{
return Ok(nameof(Get));
}
[HttpGet]
public IActionResult GetV2()
{
return Ok(nameof(GetV2));
}
В приведенном выше примере;операция GetV2 в основном является маршрутом по умолчанию для любой версии, которая явно не обрабатывается, например, HTTP GET для /api/v2/template/test.
Этот подход дает вам преимущество;а) клиенту не нужно беспокоиться о гранулярном уровне управления версиями, и б) он все еще может выполнять поэтапный рефакторинг конечных точек, который не нарушит обратную совместимость.