Semantic versioning (SemVer) gives version numbers the form MAJOR.MINOR.PATCH. Each number signals the kind of change made, helping API clients judge whether an update should remain compatible. section 3.3.3
Increment the component that matches the change:
- MAJOR for backward-incompatible API changes. section 3.3.3
- MINOR for new functionality added in a backward-compatible way. section 3.3.3
- PATCH for backward-compatible bug fixes. section 3.3.3
An API can keep older versions available while newer ones serve changed endpoints. URL-segment versioning makes those versions selectable, though maintaining them adds complexity. SemVer also permits prerelease labels and metadata; the basic three-number format is enough here. section 3.3.3
// ...
builder.Services.AddApiVersioning(options => {
options.ApiVersionReader = new UrlSegmentApiVersionReader(); #1
options.AssumeDefaultVersionWhenUnspecified = true;
options.DefaultApiVersion = new ApiVersion(1, 0);
});
builder.Services.AddVersionedApiExplorer(options => {
options.GroupNameFormat = "'v'VVV"; #2
options.SubstituteApiVersionInUrl = true; #3
});
// ...
This configuration selects URL-segment API versioning and sets 1.0 as the default. It illustrates version selection, not all three SemVer components. section 3.3.3
