SplatDev.Api.Common.ApiVersioning 2.0.2

SplatDev.Api.Common.ApiVersioning

Centralized API versioning configuration for ASP.NET Core — provides the AddSplatApiVersioning() extension method that configures Asp.Versioning.Mvc with sensible defaults: default version 1.0, assume version when unspecified, report API versions in responses, and support both query string (api-version) and header (X-API-Version) version readers.

Compatibility

Installation

dotnet add package SplatDev.Api.Common.ApiVersioning

Configuration

Basic registration

using SplatDev.Api.Common.ApiVersioning;

// Program.cs
builder.Services.AddSplatApiVersioning();

That single line configures all of the following:

• Default API version: 1.0
• Assume default version when unspecified by the client
• Report supported and deprecated API versions in response headers
• Read version from query string parameter api-version
• Read version from request header X-API-Version

Minimal API example

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddSplatApiVersioning();

var app = builder.Build();
app.MapControllers();
app.Run();

Usage

Version your controllers

using Asp.Versioning;

[ApiController]
[Route("api/v{version:apiVersion}/customers")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class CustomersController : ControllerBase
{
    [HttpGet]
    [MapToApiVersion("1.0")]
    public IActionResult GetCustomersV1()
    {
        return Ok(new { version = "1.0", data = new[] { "customer1" } });
    }

    [HttpGet]
    [MapToApiVersion("2.0")]
    public IActionResult GetCustomersV2()
    {
        return Ok(new { version = "2.0", data = new[] { "customer1", "customer2" } });
    }
}

Request via query string

GET /api/customers?api-version=1.0
GET /api/customers?api-version=2.0

Request via header

GET /api/customers
X-API-Version: 1.0

Omit version for default

GET /api/customers
# Defaults to 1.0 — no query string or header required

Report API versions in responses

When API version reporting is enabled (default), the response includes:

api-supported-versions: 1.0, 2.0
api-deprecated-versions:

Features

• One-line configuration — AddSplatApiVersioning() handles all Asp.Versioning setup
• Default version 1.0 — clients are not required to specify a version
• Assume default version when unspecified — backwards-compatible by default
• Report API versions in response headers (api-supported-versions, api-deprecated-versions)
• Query string reader — ?api-version=1.0
• Header reader — X-API-Version: 1.0
• URL path versioning — [Route("api/v{version:apiVersion}/...")] route templates supported natively
• Built on Asp.Versioning.Mvc and Asp.Versioning.Mvc.ApiExplorer
• Microsoft.AspNetCore.App framework reference for full ASP.NET Core integration

Version Reader Precedence

When multiple version sources are present, the following precedence applies:

1. Query string (api-version parameter)
2. Header (X-API-Version)

If neither is provided, the default version 1.0 is assumed.

Dependencies

SplatDev.Api.Common.ApiVersioning — part of the SplatDev.Umbraco.Plugins suite. Licensed under MIT. © SplatDev Ltda.

Changelog

2.0.2 — 2026-08-24

Removes a dashboard screenshot that showed an error toast. It was captured against a site where this plugin's API was unreachable, so it advertised a broken dashboard. No screenshot is better than a misleading one; a replacement will be taken against a working install.

2.0.1 — 2026-08-24

Package metadata only: the listing now carries an icon and search tags, and the project and repository links point at the organisation that actually hosts this code. No code changes.

2.0.0 — 2026-08-24

This package now keeps a changelog. Earlier releases predate it and are not reconstructed here — consult the repository history for those. From this version on, every release records what changed for someone using it.