How to Implement API Versioning in ASP.NET Core: Complete Guide with Best Practices (2026)

What Is API Versioning in ASP.NET Core

API versioning is a strategy that allows developers to maintain multiple versions of an API simultaneously, ensuring that changes do not break existing clients. As applications evolve, APIs often introduce new features or modify existing contracts, making versioning essential for backward compatibility and stability.

In ASP.NET Core, API versioning is typically implemented using middleware and attributes, enabling flexible control over how different versions are exposed and managed.

Why API Versioning Matters

Without versioning, even small changes to an API can cause failures in dependent systems. API versioning helps solve several critical problems:

• Prevents breaking existing clients
• Enables gradual feature rollout
• Supports multiple client versions simultaneously
• Improves long-term maintainability

For modern applications, especially microservices and public APIs, versioning is considered a best practice from the beginning of development.

Common API Versioning Strategies

ASP.NET Core supports multiple versioning approaches. Each has its own trade-offs:

1. URL Path Versioning (Recommended)

Example:

/api/v1/products
/api/v2/products

This is the most widely used method because it is clear, explicit, and easy to debug.

2. Query String Versioning

Example:

/api/products?api-version=1.0

This keeps URLs consistent but is less intuitive for users.

3. Header Versioning

Example:

api-version: 1.0

This approach keeps URLs clean but is harder to test and debug manually.

Step-by-Step: Implement API Versioning in ASP.NET Core

Step 1: Install Required Package

dotnet add package Microsoft.AspNetCore.Mvc.Versioning

Step 2: Configure Versioning (Program.cs)

builder.Services.AddApiVersioning(options =>
{
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ReportApiVersions = true;
});

This sets a default version and allows clients to omit the version if needed.

Step 3: Apply Versioning in Controller

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok("Products API V1");
    }
}

Request example:

GET /api/v1/products

Step 4: Support Multiple Versions

[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    [MapToApiVersion("1.0")]
    public IActionResult GetV1() => Ok("V1");

    [HttpGet]
    [MapToApiVersion("2.0")]
    public IActionResult GetV2() => Ok("V2");
}

This allows multiple API versions to coexist in the same controller.

Best Practices for API Versioning

1. Start Versioning Early

Do not wait until breaking changes appear—introduce versioning from day one.

2. Prefer URL Versioning for Public APIs

It is more transparent and easier for consumers to understand.

3. Maintain Backward Compatibility

Avoid removing fields or changing contracts abruptly.

4. Use Semantic Versioning

Stick to formats like v1, v1.1, or v2 to communicate changes clearly.

5. Deprecate Gracefully

Mark older versions as deprecated before removing them.

6. Document All Versions

Use Swagger/OpenAPI to clearly expose available versions.

Common Pitfalls to Avoid

• Mixing multiple versioning strategies without consistency
• Removing old versions too quickly
• Not documenting version changes
• Breaking contracts without version bump

Conclusion

API versioning in ASP.NET Core is essential for building scalable and maintainable APIs. By using proper strategies like URL versioning and implementing structured version control with tools such as Microsoft.AspNetCore.Mvc.Versioning, developers can ensure backward compatibility while continuously evolving their systems.

A well-designed versioning strategy not only protects existing users but also provides flexibility for future growth—making it a cornerstone of modern API development.