ASP.NET Core: Practical Improvements to an Existing Web API

A Web API can work correctly and still be difficult to maintain. Controllers may contain business logic, error responses may vary between endpoints, and tests may depend on implementation details. Improving an existing ASP.NET Core API does not require rewriting the application. Small, focused changes can make it more consistent and reliable.

Keep controllers focused

A controller should primarily handle HTTP concerns: receiving requests, validating request-level requirements, invoking application logic, and returning appropriate responses.

Consider an endpoint that performs several responsibilities directly:

[HttpPost]
public async Task<IActionResult> Create(
    CreateOrderRequest request)
{
    if (request.Items.Count == 0)
    {
        return BadRequest("An order must contain items.");
    }

    // Business rules, database operations,
    // and notifications all happen here.

    return Ok();
}

As the application grows, this approach can make the controller difficult to test and maintain.

Move application-specific operations into a service:

public interface IOrderService
{
    Task<int> CreateAsync(
        CreateOrderRequest request,
        CancellationToken cancellationToken);
}

The controller can then focus on the HTTP contract:

[ApiController]
[Route("api/orders")]
public sealed class OrdersController(
    IOrderService orderService) : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> Create(
        CreateOrderRequest request,
        CancellationToken cancellationToken)
    {
        var orderId = await orderService.CreateAsync(
            request,
            cancellationToken);

        return CreatedAtAction(
            nameof(GetById),
            new { id = orderId },
            new { id = orderId });
    }

    [HttpGet("{id:int}")]
    public IActionResult GetById(int id)
    {
        return Ok();
    }
}

The example illustrates separation of responsibilities; the GetById endpoint would need a real implementation in a production API.

Make error responses consistent

Clients should not need to understand a different error format for every endpoint. ASP.NET Core supports Problem Details responses, which provide a standardized structure for HTTP errors.

A typical response can communicate the status, title, and relevant details. Consistency makes it easier for frontends to display messages and for monitoring systems to classify failures.

Use validation for invalid input, suitable status codes for missing resources or conflicts, and centralized exception handling for unexpected failures. Avoid returning internal exception messages or stack traces to clients.

Use dependency injection deliberately

Register services with lifetimes that match their responsibilities:

builder.Services.AddScoped<IOrderService, OrderService>();

A scoped service is generally appropriate for application services that depend on a scoped database context. Singleton services must not capture scoped dependencies, and transient services should not be selected automatically without considering their behavior.

Add meaningful tests

A useful API test suite should cover:

• Successful requests.
• Invalid request data.
• Missing resources.
• Authorization failures.
• Business-rule violations.
• Database interactions and transaction behavior.

Unit tests are useful for isolated business rules. Integration tests help verify routing, middleware, dependency injection, serialization, and database integration.

Improve observability

Structured logging should capture useful context without exposing passwords, access tokens, or sensitive personal information. Health checks should distinguish whether the application is running from whether it is ready to handle traffic.

Conclusion

Improving an existing ASP.NET Core API is best approached incrementally. Clear service boundaries, consistent errors, appropriate dependency injection, integration tests, and useful diagnostics can substantially improve maintainability without requiring a complete rewrite.