Opting Out of Versioning using ApiVersionConventionBuilder's IsApiVersionNeutral() method does not work

[sajibcefalo]

Hello,

I have tried to make an api controller version neutral using ApiVersionConventionBuilder.IsApiVersionNeutral() method. It does not work and returns error code ApiVersionUnspecified with the message An API version is required, but was not specified when one of the api end point is called. When I make the controller version neutral using [ApiVersionNeutral] attribute, it works as expected. Is not it a bug ?

[commonsensesoftware]

Sounds like it. The expectation is that the behavior is the same regardless of whether it's the attribute, conventions, etc. I'll check both, but which platform was this - Web API or MVC Core?

[sajibcefalo]

I created it in Web API. The convention does not work in Web API

[commonsensesoftware]

Confirmed - this is a bug. I'm investigating the touch points to make sure this issue is not surfaced in multiple places. I'm pretty sure it only affects the Web API implementation.

[sajibcefalo]

@commonsensesoftware Do you know when this bug will be fixed?

[commonsensesoftware]

Apologies, I've been super busy of late. I'll see what I can get whipped out. Are you expecting this to be fixed in 2.x.x or 3.x.x? For 2.x.x, I would probably just get out some type of QFE to address the immediate problem. In review, I realized it should now be possible to pre-aggregate the API version models, which is already happening in the ASP.NET Core flavor. It's a bit more involved, but there are some good future benefits and something I'd push into 3.x.x+.

[sajibcefalo]

I need some immediate fix. I don't want to have version specific settings in each and every controller rather than I would like to have this thing configured by the convention builder. I don't think I understand what you said about QFE and pre-aggregation.

[commonsensesoftware]

The quickest recommendation I can think of to unblock you would be to create a base class for your unversioned controllers. Something like:

[ApiVersionNeutral]
public abstract class VersionNeutralController : ApiController
{
    protected VersionNeutralController() { }
}

public class MyController : VersionNeutralController
{
}

This should work with the way things are now so you aren't waiting.

I've started on the fix, which includes quite a bit of refactoring that I plan to roll into 3.0. It was unclear to me if you're using 2.x or 3.0-beta1. In terms of new features and changes, not much work has been done in Web API. You can expect the quality bar to be just as high for 3.0-beta1 as 2.x with respect to Web API. The 3.0-beta1 tag was purely to mark all the libraries with the same initial version.

Now, if you really need it for 2.x, I can pause the current work to facilitate that. In that case, I would likely do the absolute bare minimum to make things work. In tracking down the issue, it became clear that the Web API model should be refactored. The declarative (attributes) and imperative (conventions) models were not always playing nice together. This probably because Web API was the first implementation and conventions were bolted on later. I had a clean slate to start from in ASP.NET Core, which addressed many of the issues I'm seeing internally. It seemed like things were working in Web API so I never went back to clean it up. Now is a good time to do that.

Doing the right thing in this case is a lot of work. I can probably backport things to 2.x, but that just adds more time to things. I want to unblock you as soon as possible. Let me know which of the options you'd like to pursue:

1. Use a temporary workaround on your side. You can do this today without waiting. This may be inconvenient, but it's temporary. When the full fix is released in 3.0, you can upgrade.
2. Hold until I have the fix for 3.0. I'll publish 3.0-beta2 and you should be on your way.
3. I can put the full fix on hold to create a quick fix engineering (QFE) patch for 2.x. The focus here will be to do the bare minimum work to resolve this specific issue.

I have limited capacity so let me know which approach works best for you.

[sajibcefalo]

We are currently using version 2.3.0. We don't use anything other than the stable version. Do you know when the stable version 3.0 will be released? If it is released within two months then we can wait for it. Otherwise, it would be convenient for us if you can please create a QFE patch for 2.x

[commonsensesoftware]

Thanks for the response. This will definitely be resolved within 2 months. I'm actively working on it to get it resolved. Thanks for your patience.