Skip to content

ASPNET API Versioning — API Versioning Strategies in ASP.NET Core

DodaTech Updated 2026-06-28 1 min read

In this tutorial, you'll learn about ASPNET Versioning. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

ASP.NET Core API Versioning enables evolving your API surface while maintaining backward compatibility for existing consumers.

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),
        new HeaderApiVersionReader("X-API-Version"),
        new QueryStringApiVersionReader("api-version")
    );
}).AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0"), ApiVersion("2.0")]
public class ScanController : ControllerBase
{
    [HttpGet("{id}"), MapToApiVersion("1.0")]
    public IActionResult GetV1(int id) => Ok(new { Id = id, Status = "Legacy result" });

    [HttpGet("{id}"), MapToApiVersion("2.0")]
    public IActionResult GetV2(int id) => Ok(new ScanResultDto { ... });
}

Multiple version readers give API consumers flexibility while the server maintains a single codebase with versioned endpoints.

← Previous ASPNET OpenAPI and Swagger — API Documentation in ASP.NET Core Next → ASPNET Integration Testing — Comprehensive Integration Tests in .NET

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Aspnet