API versioning keeps different releases of a web API available at the same time. A new version can introduce a breaking change without immediately forcing existing clients to adapt: clients can keep using an older version while they prepare to move. This differs from deploying a web application at one address, where a new release typically replaces the previous one. section 3.3.1
A one-line change with wider consequences
Suppose a board-game mobile app needs the response DTO property Data renamed to Items. The code change is small, but websites already using Data could break. Keep the existing BoardGamesController behavior in version 1 and release the changed response in version 2. section 3.3.3
Clients need a way to request a particular version. Common choices include:
- A URL segment, such as /v1/; this is the approach used for the board-game API. section 3.3.3
- A query parameter or a version-specific route. section 3.3.3
- An Accept media-type parameter or a custom HTTP header. 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
});
// ...
The service configuration reads versions from URL segments, sets 1.0 as the default when no version is specified, and prepares versioned groups for API documentation. section 3.3.3
To make both board-game API versions available:
- Install Microsoft.AspNetCore.Mvc.Versioning and Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer, then register API versioning and its versioned API explorer. section 3.3.3
- Use versioned controller routes and declare which API version each controller supports. Put the renamed Items property in the version 2 DTO while retaining version 1 behavior. section 3.3.3
- Register separate v1 and v2 Swagger documents and endpoints. Check SwaggerUI’s definition selector to inspect each version’s documentation. section 3.3 section 3.3.3
Versioning is a trade-off, not a requirement for every change. Keeping versions online increases endpoints and code, can duplicate work, and may leave older bugs or security flaws accessible. It can also constrain later changes to database schemas, DTOs, or libraries. Weigh those costs against the compatibility clients need. section 3.3.2
Check that a new version stays separate
As a practice change, add a version 3 that supports only /v3/CodeOnDemand/Test2. Rename its addMinutes query parameter to minutesToAdd without changing version 2, and give version 3 its own swagger.json file and SwaggerUI entry. section 3.4.4
