URL-based API versioning gives each API version a distinct address. A version can appear in a domain or URL path; a common choice is a path segment such as `/v1/`. This lets an API introduce a breaking change while keeping an older endpoint available to existing clients. section 3.3.3
Keep both board-game responses working
A mobile app needs `RestDTO.Items` instead of `RestDTO.Data`, but existing websites depend on `Data`. Keep the version 1 `BoardGamesController` and add a version 2 controller with the changed response. Give each controller a `v{version:apiVersion}` route and its corresponding `ApiVersion` attribute. 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
});
// ...
Configure URL-segment reading, the default API version, and version substitution for API exploration. section 3.3.3
Publish separate v1 and v2 Swagger documents and UI entries so clients can find the appropriate endpoints. Query-string, media-type, and header versioning are alternatives to putting the version in the URL path. section 3.3.3
