API Versioning Strategies

Guidelines for effectively versioning REST APIs in .NET applications to maintain backward compatibility

8 minute read

API versioning is a critical aspect of API design and lifecycle management. It enables you to evolve your API while maintaining backward compatibility for existing clients. This documentation covers the most common versioning approaches, implementation strategies, and modern deployment patterns using API gateways.

A well-planned versioning strategy is essential from the start, as improper implementation can lead to breaking changes that render client applications unusable and significantly increase migration costs!

Why is versioning needed?

Applications evolve continuously, and their interfaces must adapt to incorporate new features, fix bugs, improve performance, and enhance security. However, when your API is consumed by other applications and developers, changes can potentially break downstream systems.

Types of API Changes

It’s important to distinguish between different types of API changes:

Non-breaking changes: Adding new endpoints, optional parameters, or response fields
Breaking changes: Removing or renaming fields, changing data types, altering endpoint behaviors

Versioning Approaches

The most common approach is multi-versioning, where multiple versions of an API are maintained in parallel. This allows client applications to migrate to newer versions according to their own schedule, reducing the risk of disruption.

When designing your versioning strategy, consider:

Discoverability: How easily clients can find available versions
URL cleanliness: Impact on RESTful URL structures
Flexibility: Ability to route requests to different implementations
Maintenance overhead: Cost of supporting multiple versions
Deprecation process: How to retire old versions gracefully

Below are the most common versioning approaches, each with implementation examples in ASP.NET Core:

1. URI Path Versioning

With URI path versioning, the version is explicitly included in the resource URI.

GET /api/v1/tasks HTTP/1.1
Host: myapi.com

GET /api/v2/tasks HTTP/1.1
Host: myapi.com

GET /api/v3/tasks HTTP/1.1
Host: myapi.com

GET /api/latest/tasks HTTP/1.1
Host: myapi.com

Implementation in ASP.NET Core

// Program.cs or Startup.cs
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
}).AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

// Controllers
[ApiController]
[Route("api/v{version:apiVersion}/tasks")]
[ApiVersion("1.0")]
public class TasksV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetTasks()
    {
        // Implementation for v1
        return Ok(new[] { new { Id = 1, Name = "Task v1" } });
    }
}

[ApiController]
[Route("api/v{version:apiVersion}/tasks")]
[ApiVersion("2.0")]
public class TasksV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetTasks()
    {
        // Enhanced implementation for v2
        return Ok(new[] { new { Id = 1, Name = "Task v2", Description = "Added in v2" } });
    }
}

Advantages

Explicit and visible: Version is clearly visible in the URL
Simple to implement: Each version can be a separate implementation
Easy to route: Different versions can be deployed as separate applications
Independent runtimes: V1 could run on .NET Framework while V2 runs on .NET 8
Isolated development: Teams can work on different versions independently
Easy decommissioning: Old versions can be retired without affecting newer versions
Documentation clarity: Each version can have its own documentation
Client simplicity: Clients explicitly know which version they’re using

Disadvantages

Non-RESTful: A resource has multiple URIs, which contradicts REST’s principle that each resource should have a unique identifier
URL pollution: Adds an extra segment to all URLs
More code: May lead to duplicate code or require additional abstraction
Maintenance overhead: Each version needs separate maintenance

Despite these disadvantages, URI path versioning is the most widely used approach due to its simplicity and explicitness.

2. HTTP Header Versioning

With header versioning, the client specifies the desired API version through a custom HTTP header or as part of standard headers like Accept.

GET /api/tasks HTTP/1.1
Host: myapi.com
X-API-Version: 1

GET /api/tasks HTTP/1.1
Host: myapi.com
Accept-Version: 2.0

GET /api/tasks HTTP/1.1
Host: myapi.com
Accept: application/json;version=3.0

Implementation in ASP.NET Core

// Program.cs or Startup.cs
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = new HeaderApiVersionReader("X-API-Version");
    // Or use media type: new MediaTypeApiVersionReader("version");
});

// Controller
[ApiController]
[Route("api/tasks")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class TasksController : ControllerBase
{
    [HttpGet]
    [MapToApiVersion("1.0")]
    public IActionResult GetTasksV1()
    {
        // Implementation for v1
        return Ok(new[] { new { Id = 1, Name = "Task v1" } });
    }

    [HttpGet]
    [MapToApiVersion("2.0")]
    public IActionResult GetTasksV2()
    {
        // Enhanced implementation for v2
        return Ok(new[] { new { Id = 1, Name = "Task v2", Description = "Added in v2" } });
    }
}

Media Type Versioning

A variation of header versioning is media type versioning, where the version is specified in the Accept header:

builder.Services.AddApiVersioning(options =>
{
    options.ApiVersionReader = new MediaTypeApiVersionReader("v");
});

GET /api/tasks HTTP/1.1
Host: myapi.com
Accept: application/json;v=1.0

Advantages

Clean URIs: Resources maintain a single, canonical URI
RESTful: Aligns better with REST principles of unique resource identifiers
Flexible routing: Different versions can be handled by the same endpoint
Content negotiation: Can leverage HTTP’s built-in content negotiation mechanisms
More centralized: Version handling can be implemented in middleware

Disadvantages

Lower visibility: Versions are hidden in headers, making debugging harder
Testing complexity: Headers must be explicitly set in API tests
Documentation challenges: Less intuitive for API consumers to understand
Difficult for browsers: Not easily testable directly in web browsers
Structure changes: Makes URL structure changes more complex to manage

Header versioning is most appropriate for mature APIs with stable resource structures and predominantly developer-oriented use cases.

3. HTTP Query Parameter Versioning

With query parameter versioning, the API version is specified as a parameter in the URL query string.

GET /api/tasks?api-version=1.0 HTTP/1.1
Host: myapi.com

GET /api/tasks?api-version=2.0 HTTP/1.1
Host: myapi.com

GET /api/tasks?api-version=latest HTTP/1.1
Host: myapi.com

Implementation in ASP.NET Core

// Program.cs or Startup.cs
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = new QueryStringApiVersionReader("api-version");
});

// Controller
[ApiController]
[Route("api/tasks")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class TasksController : ControllerBase
{
    [HttpGet]
    [MapToApiVersion("1.0")]
    public IActionResult GetTasksV1()
    {
        // Implementation for v1
        return Ok(new[] { new { Id = 1, Name = "Task v1" } });
    }

    [HttpGet]
    [MapToApiVersion("2.0")]
    public IActionResult GetTasksV2()
    {
        // Enhanced implementation for v2
        return Ok(new[] { new { Id = 1, Name = "Task v2", Description = "Added in v2" } });
    }
}

Advantages

More visible than headers: Version is visible in the URL but doesn’t affect the resource path
Easy to use: Simple for clients to change versions by modifying the query parameter
Bookmarkable: URLs with specific versions can be bookmarked or shared
Browser-friendly: Can be tested directly in a web browser
Implementation simplicity: Relatively easy to implement and maintain

Disadvantages

Caching challenges: Different versions of the same resource path can complicate caching
Less RESTful: Query parameters typically indicate filtering, not resource identification
URL pollution: Adds an extra parameter to all URLs
Optional parameter issues: Clients might omit the parameter, requiring default behavior

API Gateways and Versioning

Modern API architectures often employ API gateways to manage routing, security, and versioning. These gateways sit between clients and backend services, providing a centralized point for API management.

Role of API Gateways in Versioning

API gateways can significantly simplify versioning by:

Request routing: Directing requests to different backend services based on version
Version transformation: Translating between client-facing and internal versioning schemes
Coexistence of versions: Managing multiple API versions without code duplication
Gradual migration: Supporting incremental upgrades of backend services
Monitoring and analytics: Tracking usage across different versions

Azure Front Door for API Versioning

Azure Front Door is a global, scalable entry point that uses the Microsoft global network to create fast, secure, and highly available applications. When used for API versioning, it offers several benefits:

Client -> Azure Front Door -> [Gateway Routes by Version] -> Multiple Backend API Versions

Implementation Example with Azure Front Door

Route configuration:

{
  "routingRules": [
    {
      "name": "APIv1Route",
      "routeMatch": {
        "path": "/api/v1/*",
        "methods": ["GET", "POST", "PUT", "DELETE"]
      },
      "backendPool": {
        "name": "APIv1Backend"
      }
    },
    {
      "name": "APIv2Route",
      "routeMatch": {
        "path": "/api/v2/*",
        "methods": ["GET", "POST", "PUT", "DELETE"]
      },
      "backendPool": {
        "name": "APIv2Backend"
      }
    }
  ],
  "backendPools": [
    {
      "name": "APIv1Backend",
      "backends": [
        {
          "address": "api-v1.contoso.com",
          "weight": 100
        }
      ]
    },
    {
      "name": "APIv2Backend",
      "backends": [
        {
          "address": "api-v2.contoso.com",
          "weight": 100
        }
      ]
    }
  ]
}

Header-based routing (for header versioning):

{
  "routingRules": [
    {
      "name": "VersionedAPIRoute",
      "routeMatch": {
        "path": "/api/*",
        "headers": [
          {
            "name": "X-API-Version",
            "value": "1.0"
          }
        ]
      },
      "backendPool": {
        "name": "APIv1Backend"
      }
    }
  ]
}

Query parameter routing:

Azure Front Door can also route based on query parameters, enabling query parameter versioning at the gateway level.

Benefits of Using Azure Front Door for Versioning

Global distribution: Serve different API versions from the closest points of presence
Independent deployment: Each version can be deployed and scaled independently
Traffic splitting: Gradually migrate users from one version to another
Centralized management: Monitor and control API versions from a single place
Security enforcement: Apply consistent security policies across all versions
Health monitoring: Automatically route away from unhealthy backend instances
Rate limiting: Apply version-specific rate limits and quotas

Versioning Best Practices

Choosing the Right Strategy

Factor	URI Path	HTTP Header	Query Parameter
API visibility	High	Low	Medium
Client simplicity	High	Medium	High
RESTful purity	Low	High	Medium
Caching efficiency	High	High	Low
Testing ease	High	Low	Medium
Multiple implementations	Easy	Moderate	Moderate
Documentation clarity	High	Medium	Medium

General Recommendations

Start with versioning from day one: Even for new APIs, include version information from the beginning
Use semantic versioning: Follow MAJOR.MINOR.PATCH pattern for clear version communication
Document changes: Maintain comprehensive release notes between versions
Set clear deprecation policies: Define how long older versions will be supported
Version for breaking changes only: Don’t increment versions for backward-compatible changes
Provide migration tools: Help clients transition between versions
Monitor version usage: Track which versions are being used to inform retirement decisions
Automate testing across versions: Ensure consistent behavior for the same functionality

Conclusion

URI path versioning is recommended for most APIs due to its visibility, simplicity, and easy routing
Header versioning works well for mature APIs with stable resource structures
Query parameter versioning offers a balance between visibility and resource identification
API gateways like Azure Front Door provide powerful tools for implementing any versioning strategy at scale
The best approach depends on your specific requirements for client experience, RESTful purity, and operational simplicity