Home

Overview

Versioning is an important aspect of any mature service. Microsoft has published REST API guidelines that require all compliant services must support explicit versioning. This ensures that clients can rely on services to be stable over, while still enabling service changes and new features. Detailed information about the recommended guidance can be found in the Microsoft REST Guidelines.

The goal ASP.NET API versioning project is to adhere to the Microsoft REST Guidelines for versioning using the ASP.NET technology stack. Support is provided for the following variations of ASP.NET:

• ASP.NET Web API
• ASP.NET Web API and OData
• ASP.NET Core

Version Format

Services are versioned using a major and minor version scheme with an optional version group and status. The version format has the following forms:

[Version Group.]<Major>.<Minor>[-Status]

<Version Group>[<Major>[.Minor]][-Status]

A version group has the format of YYYY-MM-DD. This component can be used in your services to logically group service endpoints. The version status allows you to provide a condition to a version such as Alpha, Beta, RC, and so on. While the status is optional, either the version group or the major and minor versions must be specified.

Requesting a Version of a Service

By default, clients must explicitly request the version of a service via the api-version query string parameter or URL path segment per the Microsoft REST Guidelines for versioning. It is possible to customize this behavior for legacy and other non-compliant services, which will be covered in the Advanced Versioning topic.

Versioning Examples

The following outlines examples of various service version formats:

• /api/foo?api-version=1.0
• /api/foo?api-version=2.0-Alpha
• /api/foo?api-version=2015-05-01.3.0
• /api/v1/foo
• /api/v2.0-Alpha/foo
• /api/v2015-05-01.3.0/foo

Version Discovery

Requiring an explicit service version helps ensure existing clients don’t break, but we also need a way to advertise which service versions are currently supported and which versions are deprecated.

To facilitate this need, services should respond with the api-supported-versions and api-deprecated-versions, which are multi-value HTTP headers that indicate the supported and deprecated API versions, respectively. A deprecated version is still implemented, but is expected to be permanently removed in six months or more. When a version is no longer supported, it should stop being advertised.

Reporting API versions is disabled by default. Service authors can enable this behavior by setting the ApiVersioningOptions.ReportApiVersions to true.