BetterVersioning.net is an opinionated convention for the versioning of Web APIs. It allows you to add versions in a "from & until" manner instead of an attribute for every version. See the Using it chapter.
For a complete example see the example folder.
BetterVersioning.net works by adding API versions in a from & until
manner instead of manually specifying every version on a controller/method.
Specifying [From(1,0)]
would mean this controller/method is available in every version that you have added to BetterVersioning.net that is version 1.0 or higher.
Adding an [Until(5,0)]
to the same controller/method will ensure that the controller/method will no longer show up on (or after) version 5.0. (depending on options)
Managing multiple versions of an API with the regular [ApiVersion(1.0)]
and [MapToApiVersion("1.0")]
attributes can become cumbersome as the number of versions inside of your API increase.
The main reasons I initially came up with this versioning idea are:
- No need to modify controllers that are not changed when you add a new version
- Versions are automatically added/removed from controllers based on a convention
- Simplify multiple supported/deprecated versions
dotnet add package BetterVersioning.net
-
Define your API versions in the following format:
var versions = new[] { new BetterVersion(32, new ushort[]{1,2}, supported: false), new BetterVersion(33, supported: false) };
-
Modify the
builder.Services.AddApiVersioning
block by adding the BetterVersioning convention:builder.Services.AddApiVersioning(opt => { opt.AssumeDefaultVersionWhenUnspecified = true; opt.ReportApiVersions = true; opt.ApiVersionReader = ApiVersionReader.Combine(new UrlSegmentApiVersionReader(), new HeaderApiVersionReader("x-api-version"), new MediaTypeApiVersionReader("x-api-version")); opt.DefaultApiVersion = new Microsoft.AspNetCore.Mvc.ApiVersion(32, 0); // set up versions var versions = new[] { new BetterVersion(31, new ushort[]{1,2,3}), new BetterVersion(32), }; // Add the convention opt.Conventions = new BetterVersioningConventionBuilder(versions); });
-
Add a
[From]
and/or[Until]
attribute to your controller or method. The code below shows several examples.[ApiController] [Route("v{version:apiVersion}/[controller]")] [From(6)] public class BetterVersionsController : ControllerBase { [HttpGet] public string Get1() => "This endpoint was introduced in version 6"; [HttpGet("minor-range")] [Until(6, 1)] public string Get2() => "This endpoint was introduced in version 6.0 and removed after version 6.1"; [HttpGet("new")] [From(31)] [Until(33)] public string Get3() => "This endpoint was introduced in version 31 and removed after version 33"; [HttpGet("new-only-minors")] [From(34, 1)] [Until(34, 2)] public string Get4() => "This endpoint was introduced in version 34.1 and removed after version 34.2"; [HttpGet("new-till-31")] [Until(31)] public string Get5() => "This endpoint was introduced in version 6 and removed after version 31.0"; }
The main parameter for the convention is the "versions" array. This array can be declared wherever you want and consists of BetterVersion objects.
Each object is constructed with 3 main parameters:
Name | Type | Description |
---|---|---|
MajorVersion | ushort | The major version for this version |
MinorVersions | array of ushorts | The minor versions you want included in this version |
Supported | boolean | Whether the version is still supported (false would mean deprecated) |
All unsupported (/deprecated) versions are still usable but will get the deprecation message (if set up in OpenApi) applied.
When you add the convention you can (optionally) pass an options object that contains configuration options for the convention. All options are listed in the table below.
Name | Type | Description |
---|---|---|
UntilInclusive | boolean | Whether the [Until] attribute is inclusive or exclusive of the given version number. |