1.1.0

The wait is over. The official v1.1.0 packages have been released! It has taken a number of months to get all of API Explorer work you asked for, while swatting down bugs and knocking out other little features. Most of the release candidate period involved stabilization and burn-in. Many of you contributed time, blood, and sweat to help test, verify, and reproduce issues. Thank you!

All of the previous release notes apply with the following additional, final changes.

Features

• Support exploring API version parameters

This feature will ultimately enable full Swashbuckle/Swagger integration without using any custom IOperationFilter implementations. Today, the current Swashbuckle implementations do not leverage all of the API explorer information that they could, which is critical for fully documenting the API version parameter information on your behalf. There are open pull requests for all flavors of Swashbuckle to use all of the available metadata. Once that happens, you'll only need to update your Swashbuckle package references, enable Swagger, and the API version parameters will be fully documented for you. In the meantime, you use the simple SwaggerDefaultValues operation filter to bridge the gap. You can see the end-to-end solution in the examples for your flavor of ASP.NET.

Fixes

• Regression: ASP.NET Core 1.1 RC Action Selection (#133)

Breaking Changes

• If you have a custom IApiVersionReader, you now must also implement IApiVersionParameterSource

Beyond that, there are no new breaking changes from the previous beta and release candidate releases; however, for ASP.NET Core, do not forget the new configuration setup requirement:

public void Configure( IApplicationBuilder app, IHostingEnvironment env )
{
    app.UseMvc();
    app.UseApiVersioning();
}

1.1 Release Candidate

At long last, this is the release candidate for 1.1. I hadn't planned any new features, but based on feedback and bugs, a couple of features made it in. This release is expected to have 100% parity with the official 1.1 release. The purpose of the release candidate is only meant to publish a build that the community can use to verify all of the related bug fixes have indeed been resolved and there are no additional regressions.

---

Important Release Notes for ASP.NET Core

Breaking changes between official releases are carefully considered, but sometimes necessary. After careful
consideration and consultation with the ASP.NET team, a behavioral breaking change is required in API
versioning for ASP.NET Core. This is the result of multiple factors in the current routing infrastructure and
API versioning implementation. The consequences cause the API versioning extensions to incorrectly return HTTP
status code 400 or 404 in some cases. Great care was given to limit the external side effects, but all
applications will now be required to add the following to their application configurations:

public void Configure( IApplicationBuilder app, IHostingEnvironment env )
{
    app.UseMvc();
    app.UseApiVersioning();
}

This is required to make sure that intrinsic features like route constraints continue work once API versioning is
enabled. To ensure that attribute-based and convention-based routing work as expected, the call to
UseApiVersioning() should always occur after UseMvc().

Sometime in the ASP.NET Core 2.0+ timeline, I'll be working with the ASP.NET team to improve this experience and
hopefully remove this requirement in the API versioning 2.0 support.

---

Features

• Added ApiVersionFormatProvider (see version format)
• ApiVersion implementation of IFormattable now uses ApiVersionFormatProvider (see version format)
• API explorers now support options

Fixes

ASP.NET Web API

• ApiExplorer doesn't select the correct action when using MapToApiVersion (#117)
• Controllers marked as API version-neutral do not appear in Swagger (#118)
• Adding ITraceWriter breaks API versioning; also affects OData (#119)

ASP.NET Core

• HttpPut and HttpDelete template parameter names issue (#106)
• Optional parameters don't work (#122)

Breaking Changes

Since Beta 2

ASP.NET Web API

• VersionedApiExplorer.GetGroupName() is now protected; use the alternative forms instead:
  • ApiDescriptionGroupCollection.Name
  • VersionedApiDescription.GroupName
  • ApiDescription.GetGroupName() [extension method]
• Custom formatting is no longer applied to ApiVersion for the default group names

ASP.NET Core

• Removed IApiVersionGroupNameFormatter; supplanted by ApiExplorerOptions.GroupNameFormat (see version format)
• Custom formatting is no longer applied to ApiVersion for the default group names

Since 1.0

• ApiVersion format strings in ToString() are superceded by ApiVersionFormatProvider
• ASP.NET Core applications must now call UseApiVersioning() extension method in Configure

1.1.0 Beta 2

Beta 2 is here and it includes a few big ticket items that you've been asking for. The direction of the roadmap is to let this iteration burn-in a little (say - a couple of weeks) and then everything will be promoted to the official release. That should provide ample time for any remaining feedback or issues to be reported. No additional feature development is planned for this release.

Features

• Support OData for Web API 6.0 (#36)
• Add support for API explorer (#59) (see API Documentation)
  • ASP.NET Web API NuGet Package
  • ASP.NET Web API with OData NuGet Package
  • ASP.NET Core NuGet Package
• Add support for Swagger (#60) (see API Documentation)

Fixes

• ApiVersion does not compare correctly with status (#108)

Breaking Changes from Beta 1

• OData for ASP.NET Web API will only be supported for >= 6.0 from this point forward
• The IErrorResponseProvider has been refactored to make it simpler to use or replace

1.1.0 Beta 1

It's hard to believe that it's been six months since the official 1.0 release, but here we are. I'd like to thank the community for all your contributions, comments, questions, and feedback to help make this project a success. This release will mark the first significant set of roll-up changes since 1.0. This release is primarily made up of fixes, but there are a couple of new features as well; specifically, there is now out-of-the-box support for API versioning using media type negotiation as many have asked for. Keep an eye out for the updated documentation on the wiki soon. If you are an author of extensions and/or other low-level customizations, pay special attention the breaking changes that are being introduced.

Fixes

There have been a bunch of small, incremental fixes up to this point which did not mark an overall release. The following summarizes all of the fixes since 1.0, including the most recent fixes that have not previously been published in any package.

All Platforms

• Fixed reporting of API versions when conventions are used (#47)
• Fixed matching API-versioned controller action by convention (#54)
• Fixed 404 repsonse instead of 400 when API version is unspecified (#61 and #62)
• Refactored error respones to return 405 over 400 when appropriate (#65)
• Added missing support IApiVersionReader for URL segment versioning (#91)
• Fixed inherited version neutrality (#93)

ASP.NET Web API

• Fixed InvalidCastException when attribute-routed controllers have the same name (#44)

ASP.NET Web API with OData

• Fixed OData entity key value segment with custom route parameter name (#40)

ASP.NET Core

• Fixed NullReferenceException when a controller action is not matched (#52)
• Fixed use of all candidates instead of just filtered matches (#83)
• Changed the scope of ApiVersionModel constructors to make it extensible (#87)
• Reduced dependencies to Microsoft.AspNetCore.Mvc.Core (>= 1.1.1) (#66, #78, and MSA-4010983)

Features

• Added UrlSegmentApiVersionReader (related to #91)
• Added MediaTypeApiVersionReader (related to #42 and #70)
• Added IErrorResponseProvider and ErrorResponseContext (supplants CreateBadRequestDelegate)
• Added ApiVersioningProperties with extension method to get API version information from the current request

Breaking Changes

While I strive to never have breaking changes, at times they are inevitable. Careful consideration is made to limit when break changes are introduced to reduce the amount of impact. The following lists the set of surface area changes that may result in a breaking change. The vast majority of the changes are related to extensions and customizations. If those scenarios do not apply to you, then you'll very likely be unaffected.

All Platforms

• ApiVersionConventionBuilder.ApplyTo now returns bool instead of void
• ApiVersionReader:
  • is now a static class instead of an abstract class
  • no longer contains the FromQueryString or FromHeader methods
  • adds a public static Combine method to promote IApiVersionReader composition rather than inheritance
• Removed QueryStringOrHeaderApiVersionReader; it's replaced by ApiVersionReader.Combine( new QueryStringApiVersionReader(), new HeaderApiVersionReader( "api-version" ) )
• Removed GetRawRequestedApiVersion extension method and replaced it with ApiVersioningProperties().RawApiVersion
• Removed SetRequestedApiVersion extension method and replaced it with ApiVersioningProperties().ApiVersion
• Removed CreateBadRequestDelegate and replaced it with IErrorResponseProvider.BadRequest
• Removed ApiVersioningOptions.CreateBadRequest and replaced it with ApiVersioningOptions.ErrorResponses.BadRequest

ASP.NET Core

• Removed HasExplicitVersioning extension method because it's no longer used
• Removed ImplicitControllerVersionConvention because its implementation was merged into ApiVersionConvention
• Moved IControllerModelConvention implementation from ApiVersionAttribute to ApiVersionConvention (related to #87)

1.0.0

Features

• API versions can be expressed using conventions
• HTTP 400 responses related to API versioning can be customized (not recommended)

Bugs Fixed

• OData Controller Should Return 400 Instead of 404 (#17)
• ApiVersionRouteConstraint Always Returns False for Url Generation (#19)
• ASP.NET Core Controller Should Return 400 Instead of 404 (#20)
• API Version 400 Responses are Not Compliant by Default (#25)
• Convention-Based Action Routes Do Not Return 400 as Expected (#26)
• URL Segment Versioned Controllers Do Not Report All API Versions (#27)

Breaking Changes

• API version URL segements specified in the prefix for OData routes now use the same route constraint as other ASP.NET Web API routes; however, the route constraint name cannot be changed. The route contraint name must exactly be defined as {apiVersion}; for example, api/v{apiVersion}.

1.0 Release Candidate 2

Release Notes

This release has only minor enhancements and fixes in preparation for the official 1.0 release.

Changes

• Updated ApiVersion to correctly support major-only version schemes
• Added support for detecting and handling ambiguously requested API versions
• Fixed the internal action selection process in the ASP.NET Web API implementation, which incorrectly reported duplicate actions under some circumstances

1.0 Release Candidate

Release Notes

This release represents the last anticipated set of features and API changes. This release includes a few minor changes, a couple of bug fixes, and a couple of new examples.

Web API

• Updated the HttpConfiguration.GetApiVersioningOptions extension method to be public
• Added the HttpRequestMessage.GetApiVersioningOptions extension method
• Removed HttpConfiguration.GetApiVersionReader; replaced by HttpConfiguration.GetApiVersioningOptions
• Removed HttpConfiguration.GetDefaultApiVersion; replaced by HttpConfiguration.GetApiVersioningOptions
• Refactored support for the api-supported-versions and api-deprecated-versions HTTP headers to return in the multi-value format using a comma-separated list as defined in RFC 2616, §4.2

Web API and OData v4.0

• Added OPTIONS support to the $metadata endpoint
• Added support for mixing OData and non-OData services across different service API versions
• Fixed issue where $metadata may not return the correct EDMX (Issue #7)
• Fixed issue where implicitly versioned controllers are not resolved (Issue #8)