API Versioning in ASP.NET Core

Introduction

When ShopNest adds inventory fields to products, mobile apps on v1 must not break. API versioning lets you ship v2 while deprecating v1 gracefully.

After this article you will

• Version via URL, header, and query string
• Use Asp.Versioning.Http package
• Map v1 vs v2 product responses
• Document multiple versions in Swagger
• Deprecate old versions with headers

Prerequisites

• Article 36 — Building REST APIs
• ShopNest with EF Core and auth from Modules 2–4

Concept deep-dive

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"));
})
.AddApiExplorer(options => options.GroupNameFormat = "'v'VVV");

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class ProductsV1Controller : ControllerBase { ... }

[ApiVersion("2.0")]
public class ProductsV2Controller : ControllerBase
{
  // v2 includes StockQuantity in DTO
}

Deprecation: [MapToApiVersion("1.0")] + response header Deprecation: true and Sunset header per RFC.

Hands-on — ShopNest Public API with Breaking Changes

1. Install Asp.Versioning.Mvc + ApiExplorer.
2. ProductsV1 returns basic DTO; ProductsV2 adds inventory + warehouse.
3. Test: GET /api/v1/products vs GET /api/v2/products.
4. Swagger shows v1 and v2 document groups.

Common errors & best practices

• Breaking changes without version bump — breaks mobile clients in production.
• Multiple versioning strategies conflicting — pick URL or header as primary.

Interview questions

Q: URL vs header versioning?
A: URL is explicit and cache-friendly; header keeps URLs clean — many public APIs use URL (/v1/).

Q: When new major version?
A: Breaking contract changes — removed fields, changed types, URL structure.

Summary

• Never break existing clients — add version instead
• URL versioning is clearest for ShopNest public API
• v1/v2 product DTO difference is classic interview scenario
• Swagger multi-version docs aid partner developers

Previous: Building REST APIs
Next: Swagger / OpenAPI Documentation

FAQ