Версии конечных точек API

Question

Я работаю с API, который требует управления версиями.Сейчас я делаю так:

namespace MixApi.UI.Controllers
{
    [ApiVersion("1.0")]
    public class VoController : ApiController
    {
        [Route("api/v{version:apiVersion}/vo/order/")]
        public IHttpActionResult Method1() { }
    }
}

namespace MixApi.UI.Controllers.v2
{
    [ApiVersion("2.0")]
    public class VoController : ApiController
    {
        [Route("api/v{version:apiVersion}/vo/order/")]
        public IHttpActionResult Method1() { } // Improved this with new logic

        [Route("api/v{version:apiVersion}/vo/order2/")]
        public IHttpActionResult Method2() { } // New method for v2
    }
}

Однако, допустим, я собираюсь добавить новый контроллер, скажем ArticleController.Как я должен сделать это?Должно ли это быть v1 или v2?

Я думаю, что это должен быть v1, потому что это первая версия этого контроллера / конечной точки.Но потом я понимаю, что я управляю версией контроллера (конечной точки), а не самим API.Так что я немного запутался в том, как мне делать версионирование в этом случае.

Как вы, ребята, делаете это?

Answer 1

Лучше всего делать управление версиями на уровне проекта. Существует множество руководств по версионированию, которым вы можете следовать. Я хотел бы добавить ссылку на Руководство по семантическому версионированию здесь https://semver.org/

Это обеспечивает стабильность зависимых приложений.

Тем не менее. Допустим, я собираюсь добавить новый контроллер, скажем ArticleController. Как мне это сделать? Это должно быть v1 или v2?

Вы должны выпустить первую стабильную версию вашего приложения. А затем, следуйте процессу управления версиями. Таким образом, первая стабильная версия будет v1.0.0, а ревизия, подобная добавлению контроллера, будет выпущена как v1.0.1. Значительное изменение в модуле или разделе вашего приложения (например, оптимизация кода, реализация новой техники и т. Д.) Должно быть опубликовано как v1.1.x

Как вы, ребята, делаете это?

В моей организации мы ежегодно увеличиваем номер основной версии. Например, в 2018 v2.0.x, в 2019, v3.0.x и т. Д. Для выпуска основного уровня модуля мы увеличим его с v2.0.1 до v2.1.1. Если был добавлен только контроллер, мы изменим его с v2.1.1 на v2.1.2. Вы также можете обратиться к странице релизов для проекта с открытым исходным кодом для справки (пример: https://wiki.ubuntu.com/Releases)

Интересно, как мне будет управлять версиями при добавлении нового контроллера / конечной точки.

Предположим, у вас есть основной выпуск v2.x.y, а ваша конечная точка API - /api/v2/. Если вы сейчас добавите / удалите / измените контроллер, у вас будет новая сборка с v2.x.y+1. В этом случае ваша конечная точка API останется прежней: /api/v2/

Если оно не изменяется с v2.x.y+1 на v3.p.q, ваша конечная точка API должна оставаться неизменной на /api/v2/. Обратите внимание на изменения в номерах версий.

Answer 2

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

[Authorize]
[ApiVersion("3.0")]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/Users")]

Я думаю, что версию следует рассматривать как законченный продукт, поэтому пользователь будет использовать версию 2, поскольку она является самой последней (например), но внезапно они должны ссылаться на версию 1 только для новой функции.может вызвать путаницу и не кажется дружелюбным к клиенту