CODEWITHSUNDEEP
c#asp.net-web-api
Bryan
Bryan

Reputation: 3541

Versioning api endpoints

I'm working with an API that needs versioning. For now, I'm doing like this:

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
    }
}

However, let's say that I'm going to add a new controller, let's say ArticleController. How should I version it? Should it be v1 or v2?

I'm thinking it should be v1, because it's the first version of that controller/endpoint. But then I realize that I'm versioning the controller(the endpoint), and not the API itself. So I get a little bit confused of how I should do the versioning in this case.

How do you guys do it?

Upvotes: 3

Views: 1720

Answers (2)

retr0
retr0

Reputation: 744

It is best to do Versioning on Project Level. There are many versioning guides available which you can follow. I would like to slip in a reference to Semantic Versioning Guidelines here https://semver.org/

This ensures stability of the dependent applications.

However. Let's say that Im going to add a new controller, let's say ArticleController. How should I version It? Should It be v1 or v2?

You should release the first stable version of your application. And then, follow a versioning process. So First Stable version would be v1.0.0 and a revision like adding a controller would be released as v1.0.1. A major change in a module, or section of your app (like code optimization, implementing a new technique etc) should be released as v1.1.x

How do you guys do it?

At my organization, we increment the main version number each year. For example, in 2018 v2.0.x, in 2019, v3.0.x and so on. For a major module level release, we will increment it from v2.0.1 to v2.1.1. If just a controller was added, we will change it from v2.1.1 to v2.1.2. You can also refer to releases page for an Open-Source project for reference (an example: https://wiki.ubuntu.com/Releases)

I wonder how I shuld do the versioning when adding a new controller/endpoint.

Suppose, you have a major release v2.x.y and your API endpoint is /api/v2/. If you add/remove/modify a controller now, you will have a new build with v2.x.y+1. In this case your API endpoint will remain the same: /api/v2/

Unless it changes from v2.x.y+1 to v3.p.q, your API endpoint should remain the same at /api/v2/. Do notice the changes in the Version Numbers.

Upvotes: 1

Mike
Mike

Reputation: 171

You can assign multiple version to a controller and in your case I may consider doing this so if you are on version 2 and come out with a brand new controller you can assign it either one version or both.

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

I do think that version should be viewed as complete products, so a user will use version 2 as it's the latest (for example) but all of a sudden they must reference version 1 just for a new feature. could cause confusion and doesn't seem to client friendly

Upvotes: 1

Related Questions