By the end of this session, you will be able to:

• Explain why API versioning is necessary and when to introduce it
• Compare the three main versioning strategies and choose the right one
• Implement URL-based versioning in .NET using Asp.Versioning
• Mark endpoints as deprecated and communicate that to consumers

Imagine a mobile app consuming GET /api/users/{id} that returns:

{ "name": "Ahmed" }

{
  "firstName": "Ahmed",
  "lastName": "Hassan"
}

The backend can be deployed in minutes. Clients operate on entirely different timelines.

• Mobile apps go through app store review cycles — iOS App Store review can take days, and users may never update at all
• Enterprise clients have quarterly or annual release cycles and run formal regression testing before updating third-party dependencies
• Partner integrations may be maintained by entirely separate companies with their own roadmaps
• Older SDKs or scripts are often never updated — they simply keep running as long as the API behaves consistently

builder.Services.AddControllers();

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
}).AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

• DefaultApiVersion — falls back to v1.0 when no version is specified
• AssumeDefaultVersionWhenUnspecified — prevents a 400 error for clients that omit the version
• ReportApiVersions — adds api-supported-versions header to every response

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/users")]
public class UsersV1Controller : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult Get(int id) =>
        Ok(new { id, name = "Ahmed Hassan" });
}

• [ApiVersion("1.0")] declares which version this controller handles
• v{version:apiVersion} is a route constraint that Asp.Versioning resolves automatically
• The response shape exposes a single name field — this is the contract v1 clients depend on

[ApiController]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/users")]
public class UsersV2Controller : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult Get(int id) =>
        Ok(new
        {
            id,
            firstName = "Ahmed",
            lastName  = "Hassan",
            createdAt = DateTime.UtcNow
        });
}

v1 and v2 coexist in the same project. Asp.Versioning routes each request to the correct controller based on the URL segment.

Starting from a v1 UserController that returns { "id": 1, "name": "Ahmed Hassan" }, add versioning so v1 and v2 coexist:

There is no universal rule — the right duration depends on who your clients are and what their update cycle looks like.

• Only increment the major version on breaking changes — not for every new endpoint or optional field
• Semantic versioning minor bumps (v1.1) are useful for signalling additions without a breaking change

• APIs are contracts — once consumed, they cannot change without breaking clients who cannot update instantly
• Three strategies — URL path, query parameter, and header versioning; URL path is the most practical and widely expected
• Asp.Versioning makes it easy — [ApiVersion] attributes and route constraints handle all the routing automatically
• Breaking vs. non-breaking — adding optional fields is safe; removing, renaming, or adding required fields demands a new version
• Deprecate before you remove — set Deprecated = true, announce a sunset date, and give clients time to migrate
• Integer versioning is the default — simple, clear, and universally understood

Session 07 — Pagination, Filtering & Sorting

• Your API now supports multiple coexisting versions — Session 07 focuses on making those endpoints scalable for large data sets
• You will implement cursor-based and page-based pagination so GET /api/v1/tasks does not return ten thousand records at once
• Filtering and sorting are added as query parameters — tied directly to the concepts of non-breaking changes from today's session
• These techniques apply equally to every version of a versioned API

Add URL-based versioning to your Task API and introduce a v2 with a breaking response change.

What to build:

• Install Asp.Versioning.Mvc and configure it in Program.cs with default version 1.0
• Create TasksV1Controller — returns tasks with id, title, isCompleted
• Create TasksV2Controller — returns tasks with id, title, status (string: "pending" / "in-progress" / "completed"), dueDate, createdAt
• Mark v1 as deprecated using Deprecated = true

Acceptance criteria:

• GET /api/v1/tasks returns the old shape and includes api-deprecated-versions: 1.0 in the response headers
• GET /api/v2/tasks returns the new shape with the status field
• Both versions work simultaneously — neither breaks the other
• Response headers include api-supported-versions: 1.0, 2.0 on every response