abp-api

ABP Framework — API Development

Guide to ABP Framework v10.x (10.4/10.5) API development. Auto API Controllers, Dynamic C# Clients, Static C# Clients, Swagger, API Versioning, Integration Services.

Trigger

• "ABP API controller"
• "ABP auto controller"
• "ABP dynamic client"
• "ABP static client"
• "ABP swagger"
• "ABP API versioning"
• "ABP integration service"
• "ABP REST API"
• "ABP HTTP client"

---

Auto API Controllers

ABP automatically converts application services into REST API endpoints.

Configuration

[DependsOn(BookStoreApplicationModule)]
public class BookStoreWebModule : AbpModule
{
    public override void PreConfigureServices(ServiceConfigurationContext context)
    {
        PreConfigure<AbpAspNetCoreMvcOptions>(options =>
        {
            options.ConventionalControllers.Create(typeof(BookStoreApplicationModule).Assembly);
        });
    }
}

HTTP Method Mapping (Convention)

Method Prefix	HTTP Method
GetList, GetAll, Get	GET
Put, Update	PUT
Delete, Remove	DELETE
Create, Add, Insert, Post	POST
Patch	PATCH
Other	POST (default)

Route Computation

Service Method	HTTP Method	Route
GetAsync(Guid id)	GET	/api/app/book/{id}
GetListAsync()	GET	/api/app/book
CreateAsync(CreateBookDto input)	POST	/api/app/book
UpdateAsync(Guid id, UpdateBookDto input)	PUT	/api/app/book/{id}
DeleteAsync(Guid id)	DELETE	/api/app/book/{id}
GetEditorsAsync(Guid id)	GET	/api/app/book/{id}/editors

Route rules:

• Always starts with /api
• Default root path: /app
• The controller name is normalized: BookAppService → book (kebab-case, suffixes removed)
• The id parameter is added to the route: /{id}
• The action name is added (HTTP prefix and Async suffix removed)

Changing the Root Path

PreConfigure<AbpAspNetCoreMvcOptions>(options =>
{
    options.ConventionalControllers.Create(typeof(BookStoreApplicationModule).Assembly, opts =>
    {
        opts.RootPath = "volosoft/book-store";
    });
});
// Route: /api/volosoft/book-store/book/{id}

RemoteService Attribute

// Don't expose as an API controller
[RemoteService(IsEnabled = false)]
public class PersonAppService : ApplicationService { }

// Disable only specific methods
[RemoteService(IsEnabled = false)]
public override Task DeleteAsync(Guid id) { }

IRemoteService Interface

// Turn non-application-service classes into API controllers
public class MyCustomService : IRemoteService, ITransientDependency
{
    public Task<string> GetDataAsync() => Task.FromResult("data");
}

---

Dynamic C# API Client Proxies

Automatically creates a C# client proxy at runtime.

Installation

abp add-package Volo.Abp.Http.Client

Configuration

[DependsOn(
    typeof(AbpHttpClientModule),
    typeof(BookStoreApplicationContractsModule)
)]
public class MyClientModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        context.Services.AddHttpClientProxies(
            typeof(BookStoreApplicationContractsModule).Assembly
        );
    }
}

Endpoint Configuration

{
  "RemoteServices": {
    "Default": {
      "BaseUrl": "http://localhost:53929/"
    }
  }
}

Usage

public class MyClientService : ITransientDependency
{
    private readonly IBookAppService _bookAppService;
    public MyClientService(IBookAppService bookAppService) => _bookAppService = bookAppService;

    public async Task<List<BookDto>> GetBooksAsync()
    {
        return await _bookAppService.GetListAsync();
    }
}

Handled automatically:

• HTTP method, route, query string mapping
• Authentication (the access token is added to the header)
• JSON serialization/deserialization
• API versioning
• Correlation ID, tenant ID, culture headers
• Error handling (proper exceptions are thrown)

---

Static C# API Client Proxies

Proxy code is generated at development time (better performance).

Generate with the CLI

abp generate-proxy -t csharp
abp generate-proxy -t csharp --without-contracts  # Only the client proxy, without contracts
abp generate-proxy -t csharp --folder MyProxies   # Custom folder

Manual Generation

// In the HttpApi.Client project
[DependsOn(typeof(AbpHttpClientModule))]
public class MyClientModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        context.Services.AddStaticHttpClientProxies(
            typeof(BookStoreApplicationContractsModule).Assembly
        );
    }
}

Dynamic vs Static

Feature	Dynamic	Static
Performance	Runtime generation	Compile-time
Development	Easy, automatic	Re-generation required
API change	Detected automatically	Manual re-generation

---

Swagger

Configuration

[DependsOn(typeof(AbpAspNetCoreMvcModule))]
public class MyHttpApiModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        context.Services.AddAbpSwaggerGen(options =>
        {
            options.SwaggerDoc("v1", new OpenApiInfo
            {
                Title = "My API",
                Version = "v1",
                Description = "My API Description"
            });
            options.DocInclusionPredicate((docName, description) => true);
            options.CustomSchemaIds(type => type.FullName);
        });
    }

    public override void OnApplicationInitialization(ApplicationInitializationContext context)
    {
        var app = context.GetApplicationBuilder();
        app.UseSwagger();
        app.UseAbpSwaggerUI(options =>
        {
            options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API v1");
        });
    }
}

Swagger with JWT Authentication

options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
    Description = "JWT Authorization header using the Bearer scheme.",
    Name = "Authorization",
    In = ParameterLocation.Header,
    Type = SecuritySchemeType.ApiKey,
    Scheme = "Bearer"
});

options.AddSecurityRequirement(new OpenApiSecurityRequirement
{
    {
        new OpenApiSecurityScheme
        {
            Reference = new OpenApiReference
            {
                Type = ReferenceType.SecurityScheme,
                Id = "Bearer"
            }
        },
        Array.Empty<string>()
    }
});

---

API Versioning

// Versioned application service
[RemoteService]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class BookAppService : ApplicationService, IBookAppService
{
    [Obsolete("Use the new version instead")]
    public virtual Task<BookDto> GetAsync(Guid id) { }
}

// Versioned controller
[Area("app")]
[Route("api/v{version:apiVersion}/app/book")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class BookController : AbpController { }

Versioning with Swagger

context.Services.AddAbpSwaggerGenWithVersioning(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    options.SwaggerDoc("v2", new OpenApiInfo { Title = "My API", Version = "v2" });
});

---

Integration Services

Integration services are used for direct communication between modules (instead of HTTP).

// Integration service interface (in Application.Contracts)
public interface IProductIntegrationService : IIntegrationService
{
    Task<ProductDto> GetProductAsync(Guid id);
    Task CreateProductAsync(CreateProductDto input);
}

// Implementation (in Application)
[ExposeServices(typeof(IProductIntegrationService))]
public class ProductIntegrationService : ApplicationService, IProductIntegrationService
{
    private readonly IRepository<Product, Guid> _productRepository;
    public ProductIntegrationService(IRepository<Product, Guid> productRepository) =>
        _productRepository = productRepository;

    public async Task<ProductDto> GetProductAsync(Guid id)
    {
        var product = await _productRepository.GetAsync(id);
        return ObjectMapper.Map<Product, ProductDto>(product);
    }

    public async Task CreateProductAsync(CreateProductDto input)
    {
        var product = ObjectMapper.Map<CreateProductDto, Product>(input);
        await _productRepository.InsertAsync(product);
    }
}

With the IIntegrationService marker interface, ABP automatically calls these services:

• Over the local event bus (modular monolith)
• Over the distributed event bus (microservice, if a provider is configured)

---

Best Practices

1. Use Auto API Controllers — Don't write controllers manually, the convention is enough
2. Use dynamic client proxies — Don't use HttpClient manually
3. Prefer static proxies in production — No runtime overhead
4. Add JWT authentication in Swagger — Easier API testing
5. Ensure backward compatibility with API versioning — Mark old versions with [Obsolete]
6. Communicate between modules with integration services — Direct calls instead of HTTP
7. Control API exposure with the RemoteService attribute — Close off unnecessary endpoints
8. Set the root path per module — /api/my-module instead of /api/app

---

Related

• DDD — application service (the source of Auto API Controllers)
• UI — proxy consumption (Angular/Blazor/React)
• Microservices — Integration Services, static HTTP client proxy
• Authorization — endpoint authorization
• ABP Docs: https://abp.io/docs/latest/framework/api-development