4.1.0

4.1.0 is a small release with no functional changes. The key change is targeting .NET Core 3.1 for all flavors of ASP.NET Core, specifically OData, and dropping support for ASP.NET Core 2.2.

4.0.0

This marks the official release of 4.0. All of the prerelease and previous version features, as well as any fixes, roll up into this release.

Features

The following are new features and/or enhancements since 3.1.0:

All Platforms

• Add an IsDeprecated extension method (#441)
• Add API version parameter to Content-Type (#484)
• Defer reporting API version response headers
• Refactor conventions API; interfaces are defined end-to-end (see Breaking Changes)

ASP.NET Web API with OData

• Generate navigation property templates by convention (#463)
• Add UseQualifiedNames option to support qualified names in URL generation
• Remove obsolete UseQualifiedOperationNames option
• Allow route parameter name fallback (#478)
• Add support to explore all routing conventions, including $ref (#494)
• Support array URL syntax for collection parameters (#496)
• Add OData query option support for non-OData actions (#522)

ASP.NET Core

• Use Options with latest Swashbuckle integration (#422)
• Update examples to Swashbuckle 5.0.0
• Add support for ASP.NET Core 3.0

ASP.NET Core with OData

• Use Options with latest Swashbuckle integration (#422)
• Update examples to Swashbuckle 5.0.0
• Generate navigation property templates by convention (#463)
• Add UseQualifiedNames option to support qualified names in URL generation
• Remove obsolete UseQualifiedOperationNames option
• Allow route parameter name fallback (#478)
• Add support to explore all routing conventions, including $ref (#494)
• Support array URL syntax for collection parameters (#496)
• Add OData query option support for non-OData actions (#522)

Fixes

The following are fixes and patches since 3.1.0:

All Platforms

• Fix resolution of media type parameter name (#528)
• Update icon URL and support an in-package file (#544)

ASP.NET Web API

• Make updating the API version parameter description for a path route parameter reliable (#419)
• Fix enumeration of non-OWIN routes

ASP.NET Web API with OData

• Fixed type builder not keeping track of CLR types that match the EDM
• Fix selecting the assumed, default API version (#471)
• Do not override global settings when visiting EnableQueryAttribute (#488)
• Add appropriate separators for composite keys (#500)
• Support separate client and server OData route template generation (#502)
• API Explorer should support extended ODataValue<T> (#513)
• Dependency properties should keep custom attributes (#520)
• Revert to using Reflection to invoke default container configuration (#525)
• Fix key as segment URL generation (#526)
• Enable global $count query option, even though it shouldn't be needed (#567)

ASP.NET Core

• Fix endpoint policy for invalid candidate with matching API version (#423)
• Fix type test in ApiVersion model binder (#452)
• Ensure implicitly versioned ActionModel has associated ControllerModel (#519)
• Use non-generic convention builder for attribute declarations

ASP.NET Core with OData

• Fixed type builder not keeping track of CLR types that match the EDM
• Fix selecting the assumed, default API version (#471)
• Do not override global settings when visiting EnableQueryAttribute (#488)
• Add appropriate separators for composite keys (#500)
• Support separate client and server OData route template generation (#502)
• API Explorer should support extended ODataValue<T> (#513)
• Ensure implicitly versioned ActionModel has associated ControllerModel (#519)
• Dependency properties should keep custom attributes (#520)
• Fix key as segment URL generation (#526)
• Fix NullReferenceException in unversioned route constraint (#531)
• Update ModelMetadata with substituted type when necessary (#562)
• Enable global $count query option, even though it shouldn't be needed (#567)

Breaking Changes

There are no additional breaking changes since the preview release. Review the preview release for additional details.

Known Issues

The following are known issues in this release:

ASP.NET Core with OData

• Endpoint Routing is not supported
  • OData does not intrinsically support Endpoint Routing (OData/WebApi#1707)
  • Disable Endpoint Routing with services.AddMvc( options => options.EnableEndpointRouting = false );
• ASP.NET Core 3.0 is not supported (OData/WebApi#1748)

Community Contributions

Special thanks to the support and contributions from the community:

• @LuukN2 - OData Model Substitution improvements
• @brainboost - OData Model Substitution improvements

4.0.0 Preview 8 (19369.1)

Fixes

This release contains all of the fixes in 3.0 up to this point. The complete list of fixes will be provided in the official 4.0 release.

Roadmap

This release provides support for ASP.NET Core 3.0. In order to build against this preview release, you need build 3.0.0-preview8.19358.6 or higher. You will likely need to use the daily build as the latest preview build is Preview 6.

Since the latest preview build does not contain all of the required changes for API Versioning, there is no easy way to build the project for the official NuGet feed. As an official Microsoft open source project, all libraries and the NuGet package must be signed in order to publish to the public feed. This project does not have any monetary funding or budget so alternative options such as MyGet.org are not currently available. For now, the NuGet packages will be available directly from the release, which you can add to your own private feeds. The easiest way to achieve that is to simply create a folder, put the packages in it, and then add that folder as a package feed source. I expect this to be alleviated in the next ASP.NET Core 3.0 preview release, which I presume will be Preview 7 or Preview 8 sometime in the near future.

As most should already know, ASP.NET Core 3.0 will only support .NET Core 3.0. This means that support for the full .NET Framework has been dropped. I suspect it will still be a while before all developers cut completely over to .NET Core - for various reasons. The differences for API Versioning are minimal between 2.2 and 3.0. Managing separate branches between the two with fixes and features would be difficult for me to maintain.

API Versioning will multi-target between the ASP.NET Core versions to keep things in lock-step. The package will now support ASP NET.Core 3.0 on .NET Core 3.0 and continue supporting ASP.NET Core 2.x on .NET Standard 2.0. This will allow developers staying on ASP.NET Core 2.x the benefits of the latest updates and provide a smoother transition when they eventually move to ASP.NET Core 3.0. This will also continue to serve other supported scenarios such as OData, which does not yet have ASP.NET Core 3.0 support.

The long-term roadmap is not yet set, but expect that multi-target support, and ultimately support for the full .NET Framework, will be dropped around the ASP.NET Core 4.0 time frame.

Quality

In general, you can expect this release to be of high quality. With the exception of ASP.NET Core 3.0 support, all other libraries and packages are roll-ups of existing fixes and features. The Preview label will remain in-place until ASP.NET Core 3.0 stabilizes. Please continue to report any bugs you find, but expect slower turnaround times to this preview build versus the official API Versioning 3.x release.

Breaking Changes

The following are breaking changes from 3.0:

All Platforms

• The Conventions API has been refactored to enable end-to-end customization of conventions. In previous versions, you could use the built-in conventions or define a custom controller-level convention; however, the design did not appropriately extend into custom conventions for their actions. The newest revision will now allow you to define custom conventions at all levels. The change mostly involves renaming, shifting members, and adding new interfaces. In the majority of cases, your code will have source code compatibility with the new API and requires nothing more than a rebuild against the latest package.

OData (Web API and ASP.NET Core)

• The UseQualifiedOperationNames property has been removed from the ODataApiExplorerOptions and is supplanted by the UseQualifiedNames property. UseQualifiedOperationNames was marked obsolete in 3.x.

3.1.0

This is a minor release that primarily supports the Endpoint Routing feature introduced in ASP.NET Core 2.2.

This release will require you to upgrade to ASP.NET Core 2.2 if you haven't already

Features

The following are new features since 3.0.0:

ASP.NET Web API

• Updated sample projects to:
  • Use OWIN self-hosting (much faster and easier to maintain than IIS Express)
  • Use the SDK style project format
  • Use the most current C# language features

ASP.NET Core

• Support Endpoint Routing (#413)
  • All sample projects now use Endpoint Routing by default
  • The legacy routing system via IRouter is still supported
• Support default parameters values in the API Explorer (#414)
• Added IApiControllerSpecification to identify API controllers
  • The built-in ApiBehaviorSpecification matches controllers decorated with [ApiController]

interface IApiControllerSpecification
{
    bool IsSatisfiedBy( ControllerModel controller );
}

ASP.NET Core with OData

• Added ODataControllerSpecification to identify OData controllers as API controllers

Fixes

The following are fixes and patches since 3.0.0:

ASP.NET Web API with OData

• Fixed exploring query options for POST when the controller action is not an EDM action

ASP.NET Core

• Fixed possible NullReferenceException with Endpoint Routing in ApiVersionRouteConstraint

ASP.NET Core with OData

• Fixed exploring query options for POST when the controller action is not an EDM action
• Fixed a scenario where ODataAttributeRouteInfo was not generated for some actions

Breaking Changes

The following a behavioral breaking changes.

ASP.NET Core

• ApiVersioningOptions.UseApiBehavior is now true by default
  • This might result in excluding your API controllers if [ApiController] has not been applied
  • If your API controllers use convention-based routing, they will definitely be excluded because [ApiController] cannot be applied
  • Resolutions:
    1. Set ApiVersioningOptions.UseApiBehavior = false
    2. Decorated your controllers with [ApiController]
    3. Create a custom IApiControllerSpecification for your controllers and register it with services.TryAddEnumerable(ServiceDescriptor.Transient<IApiControllerSpecification, MyApiControllerSpec>());

public class MyApiControllerSpec : IApiControllerSpecification
{
    // consider all controllers that inherit from Controller to be a UI controller
    readonly Type UIControllerType = typeof( Controller ).GetTypeInfo();

    public bool IsSatisfiedBy( ControllerModel controller ) =>
        !UIControllerType.IsAssignableFrom( controller.ControllerType )
}

Figure 1: Sample custom API specification

Known Issues

The following are known issues in this release:

ASP.NET Core with OData

• Endpoint Routing is not supported
  • OData does not intrinsically support Endpoint Routing (OData/WebApi#1707)
  • Disable Endpoint Routing with services.AddMvc( options => options.EnableEndpointRouting = false );

3.0.0

This marks the official release of 3.0. All of the Beta features and fixes roll up into this release. The delta from Beta 2 is primarily fixes and enhancements.

Features

The following are new features since 3.0.0 Beta 2:

All Platforms

• Updated NuGet packages to support SourceLink

ASP.NET Web API with OData

• Support OData query options in API Explorer (#400)
• Added OriginalTypeAttribute to support resolving the original model Type after substitution

ASP.NET Core with OData

• Support OData query options in API Explorer (#400)
• Added OriginalTypeAttribute to support resolving the original model Type after substitution

Fixes

The following are fixes and patches since 3.0.0 Beta 2:

ASP.NET Core

• Fix exploring model bound ApiVersion parameter

ASP.NET Web API with OData

• Improve performance of API Explorer Model Substitution
• Fix exploring OData controllers by using ODataRoutingAttribute instead of the ODataController base class
• Fix generation of substituted types by including attributes defined by the original type

ASP.NET Core with OData

• Improve performance of API Explorer Model Substitution
• Fix exploring OData controllers by using ODataRoutingAttribute instead of the ODataController base class
• Fix generation of substituted types by including attributes defined by the original type
• Fix exploring model bound ODataQueryOptions, ODataQueryOptions<T>, and ODataPath parameters
• Correctly honor [ApiExplorerSettings(IgnoreApi = false)] (#405)

Miscellaneous

If you have cloned or forked this repository, the setups in the acceptance test suite have been refactored to maximize test server reuse. You can expect a 5-10x performance improvement in overall test run times.

Roadmap

The future roadmap currently only includes minor updates for ASP.NET Core. The 3.1 release will include support for the new Endpoint Routing feature in ASP.NET Core 2.2. For the first time, API Versioning will require the minimum version of ASP.NET Core to be 2.2 or above. The legacy method of routing will continue to be supported, but Endpoint Routing will be the new default and preferred method of routing.

3.0.0 Beta 2

The Beta 2 release marks a key milestone, which includes an array of fixes as well as new features you've been asking for. This release is expected to mark 3.0 as feature complete. Any further changes from now to the official release are only expected to include additional bug fixes or performance enhancements.

Features

The following are new features or enhancements since 3.0.0 Beta 1:

All Platforms

• API Explorer now allows including API version parameters for version-neutral APIs; still defaults to none
• Support API version interleaving across types (#230)
• Support versioning by action (#230)

ASP.NET Web API

• API version models are now pre-aggregated; improving runtime performance

ASP.NET Core

• Honor API Behaviors when applied

Fixes

The following are fixes and patches since 3.0.0 Beta 1:

All Platforms

• Fix version parsing in VersionByNamespaceConvention (#366)
• Sanitize URLs in error responses
• Clip dependent package references to their next respective major version (#376)

ASP.NET Web API

• IsApiVersionNeutral() convention does not make an API version-neutral (#322)

ASP.NET Web API with OData

• Fix MissingManifestResourceException (#331)
• Fix basic model substitution (#335)
• Support complex model substitution (#358, #382)
• Fix route prefix handling and URL segment substitution (#365)

ASP.NET Core with OData

• Fix incorrect OData action selection (#336, #337, #341)
• Fix basic model substitution (#335)
• Support complex model substitution (#358, #382)
• Fix route prefix handling and URL segment substitution (#365)

Breaking Changes

Breaking changes are always carefully considered. In designing some of the new features, it became clear that a few breaking changes were required. Given 3.0 is a major release, now was the appropriate time to introduce these changes. For most users, the changes will be transparent. The differences are most visible to those that are using the customization and extension features.

The following are breaking changes since 2.3.0 and 3.0.0 Beta 1:

All Platforms

The IApiVersionProvider now has the signature:

public interface IApiVersionProvider
{
    ApiVersionProviderOptions Options { get; }
    IReadOnlyList<ApiVersion> Versions { get; }
}

Where the options are:

[Flags]
public enum ApiVersionProviderOptions
{
    None,
    Deprecated = 1,
    Advertised = 2,
    Mapped = 4,
}

The new Mapped option disambiguates a declared API version from an API version mapped to a declaration.

The new MappingTo(ApiVersion) extension method determines whether an API is mapped and if it is explicit or implicit. The IsMappedTo(ApiVersion) extension method is now available on all platforms.

The ApiVersionModel constructors have been reduced to forms that have no dependencies or assumptions on collecting information from attributes.

ASP.NET Web API

• All other forms of retrieving or enumerating API versions has been reduced to only GetApiVersionModel extension method

Community Contributions

Special thanks to the support and contributions from the community:

• @colombod - Fix potentially unsafe URLs in error responses
• @LuukN2 - Numerous and significant fixes as well as improvements to the EDM-to-CLR type substitutions for OData

3.0.0 Beta 1

This the next major iteration of API versioning for all platforms. NuGet package distribution will begin with a Beta release will provide an opportunity to play with new features, provide feedback, and let things burn in before releasing for general availability.

The most significant new feature is support for the highly anticipated and demanded ASP.NET Core with OData implementation. It will take some time to update all of the documentation on the wiki, but in the meantime there are example projects that illustrate how to configure your application.

Features

The following are new features or enhancements since 2.3.0:

All Platforms

• Added support for multiple query string parameters (Issue #277)
• Added support to configure/use alternate route constraint name (Issue #279)
• Added support for custom API version conventions via IApiVersionConvention<T> (Issue #278)
• Added support IControllerConvention (Issue #278)
• Added support for IControllerConventionBuilder (Issue #278)
• Added the new VersionByNamespaceConvention (Issue #278)
• Added model binding support for ApiVersion (Issue #320)

ASP.NET Web API with OData

• Updated to the OData 7.0 library (no plans to continue supporting 6.x)
• Added support to update or change OData conventions during route mapping (Issue #308)

ASP.NET Core

• Added and refactored to use the new IApiVersioningFeature (Issue #280)
• Improved the catch-all route behavior (Issue #281)
• AddVersionedApiExplorer now calls the built-in AddApiExplorer implicitly
• Added support for UseApiVersioning (advanced scenario to control middleware registration)
• Added the ApiVersioningOptions.RegisterMiddleware option, which defaults to true
  • Setting this to false can be paired with UseApiVersioning for advance middleware scenarios
• All dependency injection registrations are now lazily evaluated

ASP.NET Core with OData

• Added API versioning support
• Added API Explorer support

Breaking Changes

The following are breaking changes since 2.3.0:

All Platforms

• ApiVersionConventionBuilder.ControllerConventions is now ApiVersionConventionBuilder.ControllerConventionBuilders
  • ApiVersionConventionBuilder.ControllerConventions now refers to a collection of the new IControllerConvention interface

ASP.NET Web API

• ApiVersionRequestProperties.RawApiVersion was renamed to ApiVersionRequestProperties.RawRequestedApiVersion (for parity with ASP.NET Core feature)
• ApiVersionRequestProperties.ApiVersion was renamed to ApiVersionRequestProperties.RequestedApiVersion (for parity with ASP.NET Core feature)

ASP.NET Web API with OData

• Instances of the System.Web.OData namespace were updated to Microsoft.AspNet.OData (also has parity with OData 7.0 and ASP.NET Core)
• VersionedODataModelBuilder.ModelBuilderFactory now uses new ODataConventionModelBuilder().EnableLowerCamelCase() by default

ASP.NET Core

• AddVersionedApiExplorer is now a IServiceCollection extension method instead of a IMvcCoreBuilder extension method
• AddApiVersioning no longer implicitly calls AddMvcCore (it doesn't have an actual dependency on it)
• IApiVersionRoutePolicy no longer implements IRouter; the old RouteAsync method is now Evaluate(RouteContext, ActionSelectionResult)
• ApiVersionConvention has been removed and replaced by ApiVersionCollator (Issue #301)

2.3.0

The 2.3.0 release is a roll-up release that contains a number of fixes and minor enhancements. This is the official demarcation line before the transition to the forthcoming 3.0.0 release.

Fixes

The following are fixes and patches from 2.0.0 - 2.3.0:

All Platforms

• Corrected name AddParmeters to AddParameters in IApiVersionParameterSource (NOTE: potentially breaking)
• Fixed ApiVersion.GetHashCode() (Issue #229)
• Fixed reported API version parameter for API version-neutral actions
• Fixed 405 response instead of 400 with assume default version when unspecified (Issue #254)

ASP.NET Web API

• Fixed IControllerConfiguration recursion (Issue #313)

ASP.NET Web API with OData

• Fixed by convention route path generation for the key parameter (Issue #226)
• Fixed action selection in the attribute routing convention (Issue #201)
• Fixed matching of OData operations (e.g. actions and functions)
• Fixed convention-based link generation (Issue #265)
• Fixed route name lookup when hosted in IIS (Issue #302)

ASP.NET Core

• Fix selection of actions without an API version model (ex: Razor Pages) (Issue #189)
• Use a concrete type instead of a dictionary for error responses (Issue #195)
• Fixed NullReferenceException when an explored parameter does not have model metadata (Issue #250)
• Fixed CPU pegged at 100% (Issue #306)

Features

The following are minor features and enhancements from 2.0.0 - 2.3.0:

All Platforms

• Added non-generic API version conventions (Issue #196)
• Added IReportApiVersions service (Issue #187)
• Support reporting API versions on unmatched requests (Issue #187)
• Added API version substitution in explored actions (Issue #247)
• Make base method ApplyTo virtual for built-in convention builders (Issue #258)
• Enable code and package signing (Issue #274)

ASP.NET Web API with OData

• Support by convention route path generation for composite keys (Issue #226)
• Support qualified operation names
• Added partial model types in explored actions
• Report API versions before executing an action instead of after (Issues #274, #290)

ASP.NET Core

• Improve logging for ambiguous actions (Issue #248)
• Pre-aggregate API version models (Issue #306)

2.0.0

This is another minor release with respect to changes, but includes the much anticipated and highly demanded support for ASP.NET Core 2.0. There are no visible API or behavioral changes in this release.

Fixes

The following are fixes addressed in the current release:

ASP.NET Web API

• Fixed API Explorer cloning of supported media types (related to #164)

ASP.NET Core

• Inconsistent handling of 405 on API version-neutral endpoints (#159)
• RouteData is unavailable via IRoutingFeature in HttpContext.Features (#176)

Features

The following are new or updated features in the current release:

ASP.NET Core

• Added support for ASP.NET Core 2.0
• ASP.NET Core implementations now target .NET Standard 2.0

1.2.0

This is quick, minor release, but with a significant reversion. The 1.1.0 release required ASP.NET Core users to add app.UseApiVersioning(); to their startup configurations. This was really easy to miss and a hung a lot of people up. Unfortunately, that was a required change to fix issues in 1.0.0 for some users and I had yet to find a good way to handle the scenario or fail explicitly when the configuration was missing by the time of release.

I'm happy to report for ASP.NET Core users that I've found a way to inject the behavior required by app.UseApiVersioning(); without actually making you call it. Apologies to early 1.1.x adopters who went through the pain of discovering this was needed, adding it, and now having to remove it. Ultimately, I feel this is the best decision for all users long term. Since current adoption of 1.1.x is only around 1% of 1.0.x, most people who upgrade will never see or deal with the related issues. I have subsequently updated all wiki topics and unlisted the 1.1.x NuGet packages so that users that upgrade will never encounter these issues.

Fixes

The following are fixes addressed in the current release

ASP.NET Web API

• Improve automatically cloning of MediaTypeFormatter instances; affects API versioning by media type (#156)

ASP.NET Core

• Address possible NullReferenceException building allowed HTTP methods
• Update action for routes with overlapping route templates (#147 and #148)

Breaking Changes

The following are breaking changes in the current release

ASP.NET Core

• Remove the need for and use of UseApiVersioning; affects >= 1.1.0-rc and < 1.2.0 only (#152)