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.

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.

When versioning by URL segment, the v prefix is neither required nor part of the API version.

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

The ApiVersion implements IFormattable and uses the ApiVersionFormatProvider for formatting by default. The following table outlines the supported format specifiers.

var apiVersion = new ApiVersion( 1, 0 );
Console.WriteLine( "Welcome to version " + apiVersion.ToString( "V" ) );

apiVersion = new ApiVersion( 1, 1, "Beta" );
var message = string.Format( "Welcome to version {0:VV}{0:' ('S')'}", apiVersion );
Console.WriteLine( message );

apiVersion = new ApiVersion( 2, 0 );
message = string.Format( "Welcome to version {0:VV}{0:' ('S')'}", apiVersion );
Console.WriteLine( message );

// Output: Welcome to version 1
// Output: Welcome to version 1.1 (Beta)
// Output: Welcome to version 2.0