commonsensesoftware
commented
6 years ago A few people have asked about it, but I've never seen anyone implement it - yet. Believe it or not, it's relatively simple to setup. The real challenge is coming up with a namespace naming convention that the compiler (say C#) will be happy with. I would suggest the following BNF format:
'v' : [<year> '-' <month> '-' <day>] : [<major[.minor]>] : [<status>]
This would preserve full fidelity with the API version conventions with albeit ugly namespaces. Here's a few examples:
namespace Contoso.Api.v1.Controllers { }-> "1.0"namespace Contoso.Api.v1_1.Controllers { }-> "1.1"namespace Contoso.Api.v0_9_Beta.Controllers { }-> "0.9-Beta"namespace Contoso.Api.v2018_04.Controllers { }-> "2018-04-01"namespace Contoso.Api.v2018_04_01_Beta.Controllers { }-> "2018-04-01-Beta"namespace Contoso.Api.v2018_04_01_1_0_Beta.Controllers { }-> "2018-04-01-1.0-Beta"
To parse this, I would use an extension method like this (mind the nasty regular expression):
static class TypeExtensions
{
internal static ApiVersion GetApiVersion( this Type controllerType )
{
// 'v' : year-month-day : major[.minor] : status
// ex: v2018_04_01_1_1_Beta
const string Pattern =
@"[vV](\d{4})?_?(\d{2})?_?(\d{2})?_?(\d+)?_?(\d*)_?([a-zA-Z][a-zA-Z0-9]*)?";
var match = Regex.Match( controllerType.Namespace, Pattern, RegexOptions.Singleline );
var value = new StringBuilder();
if ( match.Groups[1].Success && match.Groups[2].Success && match.Groups[3].Success )
{
value.Append( match.Groups[1].Value );
value.Append( '-' );
value.Append( match.Groups[2].Value );
value.Append( '-' );
value.Append( match.Groups[3].Value );
}
if ( match.Groups[4].Success )
{
if ( value.Length > 0 )
{
value.Append( '-' );
}
value.Append( match.Groups[4].Value );
if ( match.Groups[5].Success )
{
value.Append( '.' );
if ( match.Groups[5].Length > 0 )
{
value.Append( match.Groups[5].Value );
}
else
{
value.Append( '0' );
}
}
}
if ( match.Groups[6].Success && value.Length > 0 )
{
value.Append( '-' );
value.Append( match.Groups[6].Value );
}
return ApiVersion.Parse( value.ToString() );
}
}Now that you have a way to get an API version by convention from the namespace, you can use the API versioning conventions to configure the application. This is suprisingly easy to do using:
configuration.AddApiVersioning(
options =>
{
options.ReportApiVersions = true;
var services = configuration.Services;
var assembliesResolver = services.GetAssembliesResolver();
var controllersResolver = services.GetHttpControllerTypeResolver();
var controllers = controllersResolver.GetControllerTypes( assembliesResolver );
var conventions = options.Conventions;
foreach ( var controller in controllers )
{
conventions.Controller( controller ).HasApiVersion( controller.GetApiVersion() );
}
} );I was able to apply this change and make it work with the existing By Namespace Example with minimal effort.
In general, the right thing just happens. Any explicit attribute definitions will still be honored if they are present. This will result in a union for the conventions applied to a controller. In terms of maintenance, there's some addition things to consider:
- Refactoring/renaming a namespace could have dire consequences. Do so with caution.
- Version interleaving is still possible using explicit attributes, but it's messy. I would avoid this.
- Deleting a controller or namespace deletes the service, which is honestly probably what you want.
- If you support side-by-side (SxS) pre-release versions in independent namespaces, it will definitely work, but it could be painful to maintain. This might be the one and only case where you change a namespace. In order words, you work with a namespace suffix like "_Beta", etc until you are ready to transition to production-ready. How you do this is up to you. You might want SxS for early adopters or you just might cut over to the release version.
I've often thought this would be a pretty useful feature. Having proven to myself that it could work and is generally what large, mature service codebases will want, I think I might queue this up as a new feature in the next major release. I think you'd simply opt into the feature with a new option. Something like options.DeriveApiVersionFromType = true. Until then, you have all the extensibilty points to make this work now. :)
nirzamir
Hi,
Consider a namespace-based versioning of the same controllers/models (like in the code examples here). I was thinking of using convention-based versioning according to the namespace of each controller - go over all controllers, extract the version from their namespace, and version the controller with that version. This way, when I'm working on a new version, I replicate the current version to a new folder, refactor the namespaces, and that's it.
Will that work? Did anyone try it (both code-wise and maintenance-wise)? Any #implementation tips are welcome... I'm using ASP.Net Web API.
Thank you! Nir