版本控制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

您可以为控制器分配多个版本，在您的情况下，我可能会考虑这样做或两者。

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

我确实认为该版本应该被视为完整产品，因此用户将使用版本2，因为它是最新产品（例如），但突然之间，它们必须仅参考版本1仅用于新功能。可能会引起混乱，似乎对客户友好

Answer 2

最好在项目级别上进行版本操作。您可以遵循许多版本的指南。我想在此处参考语义版本指南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/上保持不变。请注意版本号的更改。