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.

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

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

Custom API Version Format Strings

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

Format Specifier	Description	Examples
F	Full API version as [group version][.major[.minor]][-status]	2017-05-01.1-RC -> 2017-05-01.1-RC
FF	Full API version with optional minor version as [group version][.major[.minor,0]][-status]	2017-05-01.1-RC -> 2017-05-01.1.0-RC
G	Group version as yyyy-MM-dd	2017-05-01.1-RC -> 2017-05-01
GG	Group version as yyyy-MM-dd with status	2017-05-01.1-RC -> 2017-05-01-RC
y	Group version year from 0 to 99	2001-05-01.1-RC -> 1
yy	Group version year from 00 to 99	2001-05-01.1-RC -> 01
yyy	Group version year with a minimum of three digits	2017-05-01.1-RC -> 017
yyyy	Group version year as a four-digit number	2017-05-01.1-RC -> 2017
M	Group version month from 1 through 12	2001-05-01.1-RC -> 5
MM	Group version month from 01 through 12	2001-05-01.1-RC -> 05
MMM	Group version abbreviated name of the month	2001-06-01.1-RC -> Jun
MMMM	Group version full name of the month	2001-06-01.1-RC -> June
d	Group version day of the month, from 1 through 31	2001-05-01.1-RC -> 1
dd	Group version day of the month, from 01 through 31	2001-05-01.1-RC -> 01
ddd	Group version abbreviated name of the day of the week	2001-05-01.1-RC -> Mon
dddd	Group version full name of the day of the week	2001-05-01.1-RC -> Monday
v	Minor version	2001-05-01.1-RC -> 1 1.1 -> 1
V	Major version	1.0-RC -> 1 2.0 -> 2
VV	Major and minor version	1-RC -> 1 1.1-RC -> 1.1 1.1 -> 1.1
VVV	Major, optional minor version, and status	1-RC -> 1-RC 1.1 -> 1.1
VVVV	Major, minor version, and status	1-RC -> 1.0-RC 1.1 -> 1.1 1 -> 1.0
S	Status	1.0-Beta -> Beta
p	Padded minor version with default of two digits	1.1 -> 01 1 -> 00
p[n]	Padded minor version with N digits	p2: 1.1 -> 01 p3: 1.1 -> 001
P	Padded major version with default of two digits	2.1 -> 02 2 -> 02
P[n]	Padded major version with N digits	P2: 2.1 -> 02 P3: 2.1 -> 002
PP	Padded major and minor version with a default of two digits	2.1 -> 02.01 2 -> 02.00
PPP	Padded major, optional minor version, and status with a default of two digits	1-RC -> 01-RC 1.1-RC -> 01.01-RC
PPPP	Padded major, minor version, and status with a default of two digits	1-RC -> 01.00-RC 1.1-RC -> 01.01-RC

Example Usage

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