Intent.AspNetCore.Versioning

Apply versioning strategies to ASP.NET Core APIs for managing endpoint evolution.

What This Module Does

This module enables API versioning, allowing you to support multiple API versions simultaneously and evolve your API without breaking existing clients.

When enabled, you can:

  • Define different versions of the same endpoint
  • Support clients on older API versions while developing newer versions
  • Deprecate old API versions with clear migration paths
  • Add new operations in newer versions

Generated Artifacts

API Versioning Configuration

  • ApiVersioningConfiguration - Sets up versioning service in dependency injection
  • ApiVersionSwaggerGenOptions - Configures Swagger/OpenAPI to display all API versions

Controller Attributes

For each versioned endpoint:

  • [ApiVersion("1.0")] - Marks endpoint as version 1.0
  • [ApiVersion("2.0")] - Marks endpoint as version 2.0
  • Support multiple versions on same endpoint: [ApiVersion("1.0"), ApiVersion("2.0")]

API Version Mapping

Supports multiple versioning schemes:

  • URL Path - /api/v1/endpoint, /api/v2/endpoint
  • Query String - ?api-version=1.0
  • HTTP Header - X-Api-Version: 1.0
  • Media Type - application/vnd.myapi.v1+json

Key Design Patterns

Version-Specific Endpoints

Different implementations per version:

// Version 1.0 - older implementation
[ApiVersion("1.0")]
public async Task<ActionResult<UserV1Dto>> GetUser(int id) { }

// Version 2.0 - enhanced implementation
[ApiVersion("2.0")]
public async Task<ActionResult<UserV2Dto>> GetUser(int id) { }

Deprecation Marking

Mark old versions for removal:

  • [Deprecated] - Indicates version is deprecated
  • Swagger shows deprecation warnings to API consumers
  • Clear migration timeline for clients

Default Version

Define default API version:

  • When no version specified in request, default version used
  • Provides backward compatibility for unaware clients
  • Typically set to the oldest supported version

Customization Points

Versioning Scheme Selection

Via factory extensions:

  • ControllerInstaller - Applies version attributes to controllers
  • Choose URL path, query string, or header-based versioning

Version Configuration

Customize via ApiVersioningConfiguration settings:

  • Supported Versions - List of versions to support (e.g., 1.0, 2.0, 3.0)
  • Default Version - Version used when none specified
  • Deprecated Versions - Versions marked for removal

Swagger Generation

Via ApiVersionSwaggerGenOptions:

  • Document per Version - Separate Swagger docs for each version
  • Description - Version-specific descriptions
  • Deprecated Indicator - Visual marking of deprecated versions

Versioning Strategies Comparison

URL Path Versioning (Most Common)

  • Pros: Clear in URL, easy to debug, SEO-friendly
  • Cons: URL structure changes per version
  • Example: /api/v1/products, /api/v2/products

Query String Versioning

  • Pros: Single base URL, backward compatible
  • Cons: Less discoverable, easily overlooked
  • Example: GET /api/products?api-version=1.0

Header-Based Versioning

  • Pros: Clean URLs, semantic versioning
  • Cons: Not visible in browser, harder to test manually
  • Example: X-Api-Version: 1.0 header

Content Negotiation

  • Pros: Standards-based, follows REST principles
  • Cons: Complex, rarely used in practice
  • Example: Accept: application/vnd.myapi.v1+json

When To Use

Use API Versioning when:

  • Your API is public or consumed by multiple clients
  • You need to evolve API without breaking existing clients
  • You support long-term backward compatibility requirements
  • You have clear contracts with API consumers

Don't use when:

  • Building internal APIs with single code deployment
  • All clients update simultaneously
  • API is consumed only by first-party applications
  • Breaking changes acceptable with client updates
  • Intent.Metadata.WebApi - HTTP metadata for versioning