Building Clean APIs with ASP.NET Core and Entity Framework

Building Clean APIs with ASP.NET Core

Best practices for designing maintainable, scalable, and secure REST APIs

Creating an API that works is easy. Creating an API that is maintainable, testable, and pleasant to consume is an art. In the .NET ecosystem, ASP.NET Core combined with Entity Framework (EF) Core gives us a powerful toolkit, but it's up to us to use it wisely.

This guide covers the essential patterns for building clean, professional-grade APIs, moving beyond simple CRUD to robust enterprise architecture.

1. Separation of Concerns: The Service Layer

One of the most common mistakes is putting business logic directly inside Controllers. This makes code hard to test and reuse. Instead, aim for a clear layered architecture.

The Onion Architecture: Dependencies point inwards.

❌ The Bad Way (Fat Controller)

[HttpPost]
public IActionResult CreateOrder(OrderDto dto) {
    // Validation logic mixed with business logic
    if(dto.Amount < 0) return BadRequest();
    
    var order = new Order { ... };
    _dbContext.Orders.Add(order); // Direct DB access in controller
    _dbContext.SaveChanges();
    return Ok(order);
}

✅ The Clean Way (Service Pattern)

[HttpPost]
public async Task<IActionResult> CreateOrder(OrderDto dto) {
    // Controller only handles HTTP concerns
    var result = await _orderService.CreateOrderAsync(dto);
    return Ok(result);
}

2. Global Error Handling with Middleware

Don't wrap every controller action in a try-catch block. It clutters your code. Instead, use Middleware to catch exceptions globally and return a standardized error response.

The Request Pipeline: Logic flows through middleware layers.

public class ExceptionMiddleware
{
    private readonly RequestDelegate _next;

    public ExceptionMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext httpContext)
    {
        try
        {
            await _next(httpContext);
        }
        catch (Exception ex)
        {
            await HandleExceptionAsync(httpContext, ex);
        }
    }

    private Task HandleExceptionAsync(HttpContext context, Exception exception)
    {
        context.Response.ContentType = "application/json";
        context.Response.StatusCode = (int)HttpStatusCode.InternalServerError;

        return context.Response.WriteAsync(new ErrorDetails()
        {
            StatusCode = context.Response.StatusCode,
            Message = "Internal Server Error from the custom middleware."
        }.ToString());
    }
}

3. Validation with FluentValidation

Data annotations (Attributes) can get messy. FluentValidation allows you to separate validation rules from your models, keeping your DTOs clean.

public class OrderValidator : AbstractValidator<OrderDto> 
{
    public OrderValidator() 
    {
        RuleFor(x => x.ProductName).NotEmpty();
        RuleFor(x => x.Amount).GreaterThan(0).WithMessage("Price must be positive");
    }
}

4. Use DTOs (Data Transfer Objects)

Never expose your database entities directly to the API client. It creates a tight coupling between your database schema and your public interface.

Scenario: You add a `PasswordHash` column to your User table. If you return the Entity directly, you just leaked everyone's password hashes!

Always map your Entites to DTOs. Libraries like AutoMapper or manual mapping work great.

Conclusion

Building clean APIs is about discipline. By separating concerns, implementing global error handling, and using DTOs, you create a codebase that your team will enjoy working on for years to come.