aspnet-api-versioning | add service API versioning to ASP.NET Web API | SQL Database library

When using overload CreatedAtAction(string, object), param object is not route parameters as you assume, but body content. Hence, code is looking for a route to GET api/contents which doesn't exists.

You'll need to use overload CreatedAtAction(string, object, object) where param #2 contains route params, and param #3 contains body content. So in your case, return CreatedAtAction(nameof(DownloadContent), new { id = id }, null); will work.

I was able to reproduce your issue with this controller and Postman:

Setting AssumeDefaultVersionWhenUnspecified = true is a highly abused feature. This is only meant to facilitate backward compatibility. Once you opt into API Versioning, all API controllers have some implicit or explicit API version. Assuming a version provides a mechanism to handle the "original", unnamed version that would otherwise break existing clients that don't know to include an API version in requests.

"Is there any way to tell Microsoft.AspNetCore.Mvc.Versioning that a particular method should be available regardless of versions?"

Yes, but I'm not entirely sure that is what you're looking for. An API can be version-neutral, which means it will accept any and all API versions, including none at all. This is useful for certain types of APIs such as a /ping health check or DELETE, which typically do not change over time. Such an API can be decorated with [ApiVersionNeutral]. This can be for all APIs on a controller or a specific action. Note that once you choose this path, "there can be only one."

There is not a complete picture of your setup. It appears that you are adding API versioning to an existing set of APIs. One of the primary purposes of DefaultApiVersion is to set what the default API version should be when no other information is available. If you applied no API versions whatsoever - for example, using attributes, then this would be the implicit API version of all APIs. This prevents you from having to retrofit all of your existing controllers and code. What's less obvious is that once you apply any explicit API version, then the implicit rule is ignored. This ensures that implicit versions can be sunset. The default version often does not matter. It's simply a way for you to indicate what the initial API version originally was. It's most relevant when grandfathering in existing APIs.

Given your configuration:

Q: Do I really have to add all versions to all controllers?

A: Yes. API versions are discrete. A client should get exactly what they ask for and an appropriate error response if the server cannot satisfy the request.

Q: Is there a better/correct way of handling this?

A: There are several possible options. A better or more correct way of handling things is highly subjective. There are numerous factors and the final decision may simply come down to preference.

A common misconception is that API Versioning uses attributes. It really doesn't care about attributes, it's just one possibility and one that tends to resonate with developers as metadata. You have the choice to use out-of-the-box attributes, custom attributes, out-of-the-box conventions, or your own custom conventions.

The choice of how to apply the version metadata is typically of preference and practical management. A common scenario is to organize controllers in folders by API version. In several .NET languages, the folder name translates to part or all of the corresponding namespace. This arrangement is common enough that there is an out-of-the-box VersionByNamespaceConvention for it. For details, see the documentation. The By Namespace Sample also demonstrates how to up such a project end-to-end.

API version-neutral means that an API takes any and all versions, including none at all. It can mean you don't care about the API version or that you accept a whole range that you'll deal with yourself. It is really only meant to be used with APIs that never change over time. For example, a HTTP DELETE operation typically does not change over time or across versions.

It's not 100% clear what you mean by:

"If I do not add the [ApiVersion] attribute, it defaults to the new 1.1 version and 1.0 no longer works."

There are no defaults per se. This statement seems to imply that you have set the AssumeDefaultVersionWhenUnspecified option to true. You should not do that unless you have a very good reason to do so. That is probably one of the most abused features of API Versioning. A client must know the version it is asking for. Allowing a client to not specify a version and having things transition from 1.0 to 1.1 can break the client. The server can make no assumption that it won't. This feature was meant to grandfather in existing services that didn't previously have an explicit version defined. That scenario only exists when API Versioning is first enabled. As stated above, all controllers must have one or more discrete API versions, but the original set of APIs didn't have it explicitly defined. If this feature didn't exist, then the baseline set of clients that didn't know about an API version would break.

It's solved, I'm leaving it here for future generations.

When calling CreatedAtAction, you must inform the version of the action you want to call. While this may be obvious, there's an exact way to do so:

Either capture the current version and pass it back:

Using the OData Model Configurations approach described here first add a class that derives from IModelConfiguration to your project.

Something like this:

From the incoming request you will see what the URL is, and therefore you can determine which controller it will be mapped to. Controllers are classes, and the deprecated ones are marked with the [ApiVersion(Deprecated = true)] attribute. So you can grab the controller, and with reflection you can check its attributes and see if it's deprecated. Documentation here

You generally do not version EF because - you still have only one database anyway.

You version the API because it is a "public interface", not an implementation detail. But the db is internal and IS an implementation detail.

Which is why most people will not expose EF objects via an API - they will project them to API objects (which is a way you can handle changes in the db when versioning).