API Versioning

1. The Zomato Versioning Rule

v1: GET /api/v1/restaurants → returns { id, name }

v2: GET /api/v2/restaurants → returns { id, name, isVegOnly, rating }

Result: Old app keeps hitting v1. Works fine. New app hits v2. Gets new features. Zero breaking changes.

2. Setup Versioning in.NET 8 - 4 Steps

Step 1: Install Package

dotnet add package Asp.Versioning.Mvc

Step 2: Program.cs

builder.Services.AddApiVersioning(options => {
  options.DefaultApiVersion = new ApiVersion(1, 0);
  options.AssumeDefaultVersionWhenUnspecified = true;
  options.ReportApiVersions = true; // Adds api-supported-versions header
  options.ApiVersionReader = ApiVersionReader.Combine(
      new UrlSegmentApiVersionReader(), // /api/v1/restaurants
      new HeaderApiVersionReader("X-Api-Version"), // Header versioning
      new QueryStringApiVersionReader("api-version") //?api-version=1.0
  );
}).AddMvc(); // Needed for controllers

Step 3: Version Your Controllers

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
public class RestaurantsController : ControllerBase {
  [HttpGet]
  public IActionResult GetV1() => Ok(new { Id = 1, Name = "Pizza Hut" });
}

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("2.0")]
public class RestaurantsV2Controller : ControllerBase {
  [HttpGet]
  public IActionResult GetV2() => Ok(new { Id = 1, Name = "Pizza Hut", IsVegOnly = false });
}

Step 4: Test

GET /api/v1/restaurants → v1 response
GET /api/v2/restaurants → v2 response
GET /api/restaurants → defaults to v1 because AssumeDefaultVersionWhenUnspecified = true

3. Swagger + Versioning = Pro Setup

Without this, Swagger shows all versions mixed. Fix:

dotnet add package Asp.Versioning.Mvc.ApiExplorer

builder.Services.AddApiVersioning(...)
 .AddMvc()
 .AddApiExplorer(options => {
      options.GroupNameFormat = "'v'VVV"; // v1, v2
      options.SubstituteApiVersionInUrl = true;
  });

Result: Swagger UI has dropdown: "v1" | "v2". Clean.

1. Theory: 3 Ways to Version APIs

Senior Pick: URL Path for public APIs. Header for internal microservices. Zomato + Stripe use URL Path.

2. Deprecating Old Versions - The Right Way

Can't support v1 forever. Deprecate gracefully:

[ApiVersion("1.0", Deprecated = true)]
public class RestaurantsController : ControllerBase {...}

This adds header: api-deprecated-versions: 1.0
Swagger shows v1 as "Deprecated". Frontend teams get warning.

Timeline: 1. Mark Deprecated 2. Email clients 3. Wait 6 months 4. Return 410 Gone 5. Delete code.

3. Same Controller, Multiple Versions

Don't need 2 controller files. Use MapToApiVersion:

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class RestaurantsController : ControllerBase {
  [HttpGet]
  [MapToApiVersion("1.0")]
  public IActionResult GetV1() => Ok(new { Id = 1, Name = "A" });

  [HttpGet]
  [MapToApiVersion("2.0")]
  public IActionResult GetV2() => Ok(new { Id = 1, Name = "A", Rating = 4.5 });
}

4. Version-Neutral Endpoints

/health or /ping shouldn't have version.

[ApiController]
[Route("[controller]")]
[ApiVersionNeutral] // No version
public class HealthController : ControllerBase {
  [HttpGet]
  public IActionResult Get() => Ok("Healthy");
}