Versioning

The moment something you do not deploy depends on your API, its shape is frozen for that consumer. A mobile app on people's phones cannot be updated by you. A partner's integration is on their release schedule. A scheduled job somewhere in the business was written by someone who has left.

Versioning is how you change the contract anyway: the old shape keeps working for callers who have not moved, while a new shape is available for those who have. The first decision is not which versioning scheme to use. It is telling the difference between a change that needs a version and one that does not.

var v1 = app.MapGroup("/api/v1").WithTags("v1");
var v2 = app.MapGroup("/api/v2").WithTags("v2");

// Unchanged between versions: one handler, mapped in both
v1.MapGet("/departments", DepartmentEndpoints.List);
v2.MapGet("/departments", DepartmentEndpoints.List);

// Changed in v2: fullName became a structured name object
v1.MapGet("/employees/{id:int}", EmployeeEndpoints.GetV1);
v2.MapGet("/employees/{id:int}", EmployeeEndpoints.GetV2);

// New in v2 only
v2.MapGet("/employees/{id:int}/leave-balance", EmployeeEndpoints.GetLeaveBalance);

// In EmployeeEndpoints: v1 keeps its shape by mapping from the same source
public static async Task<IResult> GetV1(int id, EmployeeService employees)
{
    var employee = await employees.FindAsync(id);
    return employee is null
        ? Results.NotFound()
        : Results.Ok(new EmployeeResponseV1(employee.Id, employee.FullName));
}

• Route groups give you the version prefix in one place, so no individual endpoint contains the string v1.
• Endpoints that did not change are mapped twice from the same handler. Duplicating the code instead is how two versions drift into two behaviours nobody intended.
• The endpoints that did change have one handler each. That is the honest cost of a version: a second code path, kept working, for as long as the old version is supported.
• Both versions read from the same service and the same entity. What differs is the response type — which is only possible because the contract was a DTO rather than the entity.
• For anything larger than this, the Asp.Versioning packages handle versioned routing, defaults and reporting supported versions in response headers. Route groups are enough to start, and they make the mechanism visible while you are learning it.

Choose the scheme before you need it, not during the release that needs it. Retrofitting a version onto an API whose callers all use unversioned paths means either breaking them or keeping the unversioned paths forever as an implicit v1. The second is what usually happens, and it is a permanent oddity in the contract for the sake of a decision that would have taken an hour.

Plan the retirement at the same time. A version with no end date is a version you maintain indefinitely, so publish what supporting an old version means: how long it stays, how you will announce deprecation, and how a caller can tell. There is a standard Sunset response header for stating the retirement date, and a Deprecation header in common use alongside it, and the announcement still needs to reach people rather than only machines.

Then keep the number of versions small. Two is manageable. Four means every bug is fixed up to four times, every security review covers four code paths, and nobody is certain which behaviour is current.