mccalltd
commented
12 years ago Hi Greg. So I looked though the commits, and made some comments that I've since deleted cause I wanted to just respond here instead, so sorry for any ghosted github alerts.
So what is your use case? How is this helpful to you? The reason I ask -- to play devil's advocate -- is why not use route prefixes and custom contraints to do this? You could define a custom constraint that wrapped up your semantic version parsing logic, which you could then apply to a url segment. A bit more verbose, but then you could put the version anywhere in your URL that you want, at the beginning, after area name and prefix, between area name and prefix.... Here's an example:
[RoutePrefix("api")]
public class SampleController : ApiController
{
// Any version will do here, so long as v is parsable as a semantic version
[GET("{v:version}/a")]
public string ActionA() {}
// v >= 1.1
[GET("{v:minVersion(1.1)}/b")]
public string ActionB() {}
// v >= 1.0 && <= 1.2
[GET("{v:minVersion(1.0):maxVersion(1.2)}/c")]
public string ActionC() {}
// v <= 1.2
[GET("{v:maxVersion(1.2)}/d")]
public string ActionD() {}
// v >= 1.3
[GET("{v:minVersion(1.3)}/d")]
public string ActionD2() {}
}or maybe something like:
// This controller contains only v1.0 routes
[RoutePrefix("api/{v:version(1.0)")]
public class SampleV1Dot0Controller : ApiController
{
[GET("a")]
public string ActionA() {}
[GET("b")]
public string ActionB() {}
}
// This controller contains only v1.1 routes
[RoutePrefix("api/{v:version(1.1)")]
public class SampleV1Dot1Controller : ApiController
{
[GET("a")]
public string ActionA() {}
[GET("b")]
public string ActionB() {}
}Will look more at the diff tomorrow. It's too late to be doing this :)
Cheers
gregmac
sksk571
vyrotek
kamranayub
I am considering adding support for versioning, but I wanted to see if there is upstream interest in this feature, or any feedback on my proposed implementation.
What I'm trying to do is version an API, but I think this is general enough that it makes sense to be part of AttributeRouting. The idea behind this is you can have your API follow semantic versioning and maintain both backwards and forwards compatibility as you release new versions. I also want to make it easy for developers to support old versions.
There would be a new RouteVersion attribute:
RouteVersionAttribute(string minVersion, string maxVersion = null). These will be compared using semantic versioning (eg, "1.9.0" is older than "1.10.1-alpha"). If null is passed, it means unbounded.You would first tell AR what "versions" you are currently supporting:
Given:
/1.0/a== a()/1.1/a== a()/1.2/a== a()/1.1/b== b()/1.2/b== b()/1.0/c== c()/1.0/d== d()/1.1/d== d()/1.2/d== d2()A route is defined for each known version according to the rules for each route. Note in my example that:
/1.0/bis not a route (because the "b" method was only introduced in version 1.1)/1.1/cand1.2/care not routes (because the d method was dropped after 1.0)/1.2/d(with a new return type)./1.3/bis not a route (because "1.3" was not supported in configuration)As a developer, if I make a version 1.3, all I need to do is update the configuration, and my methods are all automatically supported in 1.3 (unless I've explicitly defined a maxVersion). If I am removing or changing a specific route of course, I do need to go touch that one and adjust the version.
I know one reaction may be that "Gasp! I don't know if method b() is going to be supported forever!" but that is why the versions are defined in configuration. In this particular build, although there is no maxVersion for b(), AR only knows about 3 versions -- if I go to
/1.3/b, I will get a 404. If I am building version 1.3 and want to remove b() from it, I go adjust the RouteVersion attribute on b() and add "1.3" to the configuration.Similarly, it's easy to remove old versions. If I want to stop supporting version 1.0, I just have to remove that from the configuration. Hopefully I also go through and remember to remove c() but even if I don't, there would be no way to call it any more.
It's also possible to specify Min/MaxVer on the RouteVersioned attribute, in which case they are used unless explicitly overridden in the route attributes. One exception is if you specify eg, a MinVer in the RouteVersioned attribute, null does not override it.
Versions come after areas (if used) but before prefixes. In the future this may be configurable.
Controllers without [RouteVersioned] specified work exactly like normal controllers. RouteVersionedAttribute is inheritable so it can be defined in a base controller and thus applied everywhere.
The default, if no versions are specified, is min=null and max=null, which means that the route is available in all configured versions.
Any other feedback is welcome, but I intend to start working on this relatively soon. I'm also open to creating this as an optional add-on project but I think it would still require some extension points in core AR to support that scenario (and frankly, that may be way too complex -- and considering localization and areas and prefixes are built in, versioning makes sense to me as well).