Skip to content
Skills Library
Programming · Building & coding

version-http-apis

/version-http-apis

Add API versioning to ABP HTTP APIs so multiple versions of the same service coexist behind static client proxies. USE FOR: AddAbpApiVersioning, query/header/media-type version readers, attaching ApiVersions to conventional controllers, ICurrentApiVersionInfo runtime version switching, the versioned API explorer. DO NOT USE FOR: exposing services as controllers in the first place (use expose-http-apis); Swagger UI / OpenAPI doc setup (use configure-swagger-openapi); generating or calling C# client proxies (use consume-remote-services).

Repository
abp-skills ↗
Licence
MIT
Last repository change
05.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 05.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Add API versioning to ABP HTTP APIs so multiple versions of the same service coexist behind static client proxies. USE FOR: AddAbpApiVersioning, query/header/media-type version readers, attaching ApiVersions to conventional controllers, ICurrentApiVersionInfo runtime version switching, the versioned API explorer. DO NOT USE FOR: exposing services as controllers in the first place (use expose-http-apis); Swagger UI / OpenAPI doc setup (use configure-swagger-openapi); generating or calling C# client proxies (use consume-remote-services).

Original author description

Add API versioning to ABP HTTP APIs so multiple versions of the same service coexist behind static client proxies. USE FOR: AddAbpApiVersioning, query/header/media-type version readers, attaching ApiVersions to conventional controllers, ICurrentApiVersionInfo runtime version switching, the versioned API explorer. DO NOT USE FOR: exposing services as controllers in the first place (use expose-http-apis); Swagger UI / OpenAPI doc setup (use configure-swagger-openapi); generating or calling C# client proxies (use consume-remote-services).

How it works

  1. When to Use
  2. When Not to Use
  3. ⚠️ Read this first: URL-path versioning breaks the static proxies
  4. Enable versioning
  5. Attribute-routed controllers
  6. Conventional (Auto API) controllers
  7. Switch the requested version at runtime (C)
  8. Versioned API explorer / Swagger
  9. Validation
  10. Common Pitfalls
Original SKILL.md headings · 188 lines, 831 words
SKILL.md preview
---
name: version-http-apis
description: >
  Add API versioning to ABP HTTP APIs so multiple versions of the same service coexist behind static client proxies.
  USE FOR: AddAbpApiVersioning, query/header/media-type version readers, attaching ApiVersions to conventional controllers, ICurrentApiVersionInfo runtime version switching, the versioned API explorer.
  DO NOT USE FOR: exposing services as controllers in the first place (use expose-http-apis); Swagger UI / OpenAPI doc setup (use configure-swagger-openapi); generating or calling C# client proxies (use consume-remote-services).
license: MIT
---

# Version ABP HTTP APIs

ABP integrates the [ASP.NET API Versioning](https://github.com/dotnet/aspnet-api-versioning/wiki)
library and adapts it to Auto (Conventional) API Controllers and the static C# / JavaScript
client proxies. You enable it once, then either attach versions per controller (attribute
routing) or per assembly (conventional controllers).

## When to Use

- Serving `1.0` and `2.0` (etc.) of the same service side by side.
- Attaching versions to conventional controllers via `ConventionalControllers.Create(...)`.
- Switching the requested version from C# at runtime with `ICurrentApiVersionInfo`.
- Building one Swagger document per discovered version.

## When Not to Use

- **Just exposing a service as a controller** (no versions yet) — use **expose-http-apis**.
- **Swagger UI / OpenAPI wiring** beyond the versioned explorer — use **configure-swagger-openapi**.
- **Generating or calling client proxies** — use **consume-remote-services**.

## ⚠️ Read this first: URL-path versioning breaks the static proxies

The static C# and JavaScript client proxies **cannot** carry the version in the URL path/segment.
Use **query-string versioning** (`?api-version=2.0`) — the default ABP proxies emit.

Grounding: `ApiVersionInfo.ShouldSendInQueryString()` returns `!BindingSource.IsIn("Path")`
(`framework/src/Volo.Abp.Http.Client/Volo/Abp/Http/Client/ClientProxying/ApiVersionInfo.cs`),
so a `Path` binding source is never appended to the proxy request. The versioning doc says the
same: this feature "does not compatible with URL Path Versioning, we suggest to use Versioning
via the Query String" (`docs/en/framework/api-development/versioning.md`).

## Enable versioning

`AddAbpApiVersioning` is an `IServiceCollection` extension in `Microsoft.Extensions.DependencyInjection`
(`framework/src/Volo.Abp.AspNetCore.Mvc/.../AbpApiVersioningExtensions.cs`). Its signature:

```csharp
IApiVersioningBuilder AddAbpApiVersioning(
    this IServiceCollection services,
    Action<ApiVersioningOptions>? apiVersioningOptionsSetupAction = null,
    Action<MvcApiVersioningOptions>? mvcApiVersioningOptionsSetupAction = null)
```

`ApiVersioningOptions` / `MvcApiVersioningOptions` and the properties set below
(`ReportApiVersions`, `AssumeDefaultVersionWhenUnspecified`) come from the ASP.NET API
Versioning library — they are **not** ABP types. Same for `IApiControllerFilter` /
`NoControllerFilter` (used to keep neutral/versionless APIs visible).

```csharp
public override void ConfigureServices(ServiceConfigurationContext context)
{
    // Show neutral / versionless APIs.
    context.Services.AddTransient<IApiControllerFilter, NoControllerFilter>();

    context.Services.AddAbpApiVersioning(options =>
    {
        options.ReportApiVersions = true;
        options.AssumeDefaultVersionWhenUnspecified = true;
    });

    Configure<AbpAspNetCoreMvcOptions>(options =>
    {
        options.ChangeControllerModelApiExplorerGroupName = false;
    });
}
```

The version reader (query string vs. header vs. media type) is the standard ASP.NET API
Versioning `ApiVersionReader` on `ApiVersioningOptions` — keep it on the query string when static
proxies are in play (see the warning above).

## Attribute-routed controllers

Put `[ApiVersion(...)]` (an ASP.NET API Versioning attribute) on each controller. Two controllers
sharing one `[Route]` but different versions serve as v1/v2 of the same service:

```csharp
[ApiVersion("1.0", Deprecated = true)]
[ControllerName("Book")]
[Route("api/BookStore/Book")]
public class BookController : BookStoreController, IBookAppService { /* ... */ }

[ApiVersion("2.0")]
[ControllerName("Book")]
[Route("api/BookStore/Book")]
public class BookV2Controller : BookStoreController, IBookV2AppService { /* ... */ }
```

## Conventional (Auto API) controllers

Attach versions per assembly in `PreConfigureServices`. `ConventionalControllerSetting.ApiVersions`
is a `List<ApiVersion>` (`framework/src/Volo.Abp.AspNetCore.Mvc/.../Conventions/ConventionalControllerSetting.cs`);
`ApiVersion` is an ASP.NET API Versioning type. Use `TypePredicate` to split versions by namespace:

```csharp
public override void PreConfigureServices(ServiceConfigurationContext context)
{
    PreConfigure<AbpAspNetCoreMvcOptions>(options =>
    {
        options.ConventionalControllers.Create(typeof(BookStoreWebAppModule).Assembly, opts =>
        {
            opts.TypePredicate = t => t.Namespace == typeof(v2.TodoAppService).Namespace;
            opts.ApiVersions.Add(new ApiVersion(2, 0));
        });

        options.ConventionalControllers.Create(typeof(BookStoreWebAppModule).Assembly, opts =>
        {
            opts.TypePredicate = t => t.Namespace == typeof(v1.TodoAppService).Namespace;
            opts.ApiVersions.Add(new ApiVersion(1, 0));
        });
    });
}
```

Then wire those pre-configured settings into the versioning options with the `ConfigureAbp`
extension — `ConfigureAbp(this MvcApiVersioningOptions options, AbpAspNetCoreMvcOptions mvcOptions)`
(same file as `AddAbpApiVersioning`). It reads `mvcOptions.ConventionalControllers`, calling each
setting's `MvcApiVersioningConfigurer` if set, otherwise applying its `ApiVersions` by convention
(neutral when none):

```csharp
public override void ConfigureServices(ServiceConfigurationContext context)
{
    var preActions = context.Services.GetPreConfigureActions<AbpAspNetCoreMvcOptions>();

    context.Services.AddTransient<IApiControllerFilter, NoControllerFilter>();
    context.Services.AddAbpApiVersioning(options =>
    {
        options.ReportApiVersions = true;
        options.AssumeDefaultVersionWhenUnspecified = true;
    }, options =>
    {
        options.ConfigureAbp(preActions.Configure());
    });
}
```

## Switch the requested version at runtime (C#)

When one client wants a specific version from a multi-version service, inject
`ICurrentApiVersionInfo` (`namespace Volo.Abp.Http.Client.ClientProxying`) and scope the change
with `Change(...)`. It stores an `AsyncLocal` value restored on dispose, so wrap it in a `using`:

```csharp
var current = serviceProvider.GetRequiredService<ICurrentApiVersionInfo>();
var bookService = serviceProvider.GetRequiredService<IBookV4AppService>();

using (current.Change(new ApiVersionInfo(ParameterBindingSources.Query, "4.0")))
{
    var book = await bookService.GetAsync(); // proxy adds ?api-version=4.0
}
```

- `ApiVersionInfo(string bindingSource, string version)` —
  `framework/src/Volo.Abp.Http.Client/.../ClientProxying/ApiVersionInfo.cs`.
- `ParameterBindingSources.Query` / `.Header` / `.Path` … are string consts in
  `Volo.Abp.Http.ProxyScripting.Generators.ParameterBindingSources`. Use `Query`; `Path` is
  dropped by the proxy (see the warning).

## Versioned API explorer / Swagger

Chain `.AddApiExplorer(...)` on the builder returned by `AddAbpApiVersioning` for one Swagger
document per version, then iterate `provider.ApiVersionDescriptions` to add a `SwaggerEndpoint`
each. `GroupNameFormat`, `SubstituteApiVersionInUrl`, `IApiVersionDescriptionProvider` are ASP.NET
API Versioning types (not ABP); full example in the versioning doc. Deeper Swagger setup belongs
to the **configure-swagger-openapi** skill.

## Validation

- Call the same route with `?api-version=1.0` and `?api-version=2.0`; confirm each hits the
  matching version and that `ReportApiVersions` adds `api-supported-versions` response headers.
- Confirm neutral/versionless endpoints still appear (that's the `NoControllerFilter` job).
- With generated static proxies, confirm the request carries the version on the **query string**,
  not the path.

## Common Pitfalls

- **URL-path/segment versioning silently breaks static proxies** — the proxy never sends a `Path`
  binding source. Stay on query-string versioning.
- Setting `ApiVersions` on a conventional-controller assembly does nothing unless
  `options.ConfigureAbp(preActions.Configure())` is applied to the versioning options.
- `AddAbpApiVersioning` returns an `IApiVersioningBuilder`; call `.AddApiExplorer(...)` on that
  return value — don't try to add the explorer separately.
- `ReportApiVersions`, `AssumeDefaultVersionWhenUnspecified`, `[ApiVersion]`, `ApiVersion`,
  `IApiControllerFilter`/`NoControllerFilter` are ASP.NET API Versioning symbols ABP wraps — look
  them up in that library's wiki, not the ABP API.

Versions

The database has no other skills named version-http-apis.

Database snapshot: 13.11.2026 · package version cef6b8350aa4 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100configure-swagger-openapi
    Wire up Swagger/OpenAPI for an ABP host with the Volo.Abp.Swashbuckle helpers, including OAuth/OIDC authorize flows and hiding framework endpoints. USE FOR: AddAbpSwaggerGen + UseAbpSwaggerUI setup, AddAbpSwaggerGenWithOAuth / AddAbpSwaggerGenWithOidc for interactive auth on the…
  • 100abp-api
    ABP Framework v10.x (10.4–10.6) API development: Auto API Controllers, dynamic and static C#/JS client proxies, Swagger, API versioning, Integration Services. Use when you need a REST API, controller, dynamic proxy or client generation in ABP.
  • 100abp-api
    ABP Framework v10.x (10.4–10.6) API development: Auto API Controllers, dynamic and static C#/JS client proxies, Swagger, API versioning, Integration Services. Use when you need a REST API, controller, dynamic proxy or client generation in ABP.
  • 100expose-http-apis
    Expose ABP application services as REST endpoints through Auto/Conventional API Controllers. USE FOR: publishing application services as HTTP controllers, route/verb conventions, [RemoteService] toggles, integration services and [IntegrationService]. DO NOT USE FOR: calling a…
  • 90dev-loop-api-client-generator
    Use when the user asks about generating API clients, OpenAPI/Swagger code generation, REST API client SDKs, or automating API client creation. Do NOT use for: writing API servers, or manual HTTP request code.
  • 95api-documentation-generator
    Generate OpenAPI/Swagger specifications and API documentation from code or design. Use when creating API docs, generating OpenAPI specs, or documenting REST APIs.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.