ASP.NET Core Web API is a cross-platform, open-source framework from Microsoft for building HTTP services in C#, running on Windows, Linux, and macOS. A production-ready Web API follows a layered structure: thin controllers that handle HTTP concerns, a service layer that owns business logic, DTOs that separate wire contracts from database entities, and dependency injection wiring everything together. Around that core, best practices add FluentValidation for request validation, global exception handling middleware that returns consistent ProblemDetails responses, pagination for large collections, response caching, API versioning, structured logging, health checks, and rate limiting. Applied together, these patterns keep an API maintainable as it grows, make behavior predictable for clients, and prepare the service for real production traffic. This guide walks through each practice with concrete C# code you can copy into an ASP.NET Core project.
Project Structure
text
MyApp/
├── src/
│ ├── MyApp.API/ # Web API layer
│ │ ├── Controllers/
│ │ ├── Filters/
│ │ ├── Middleware/
│ │ └── Program.cs
│ ├── MyApp.Application/ # Business logic
│ │ ├── Services/
│ │ ├── DTOs/
│ │ ├── Interfaces/
│ │ └── Validators/
│ ├── MyApp.Domain/ # Domain models
│ │ ├── Entities/
│ │ ├── Enums/
│ │ └── Exceptions/
│ └── MyApp.Infrastructure/ # Data access, external services
│ ├── Data/
│ ├── Repositories/
│ └── Services/
└── tests/
├── MyApp.UnitTests/
└── MyApp.IntegrationTests/How Should You Design Controllers?
Keep Controllers Thin
Controllers should only handle HTTP concerns. Business logic belongs in services.
csharp
// Controllers/UsersController.cs
[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
public class UsersController : ControllerBase
{
private readonly IUserService _userService;
private readonly ILogger<UsersController> _logger;
public UsersController(IUserService userService, ILogger<UsersController> logger)
{
_userService = userService;
_logger = logger;
}
/// <summary>
/// Gets all users with pagination
/// </summary>
[HttpGet]
[ProducesResponseType(typeof(PagedResult<UserDto>), StatusCodes.Status200OK)]
public async Task<ActionResult<PagedResult<UserDto>>> GetUsers(
[FromQuery] PaginationParams pagination,
CancellationToken cancellationToken)
{
var users = await _userService.GetUsersAsync(pagination, cancellationToken);
return Ok(users);
}
/// <summary>
/// Gets a user by ID
/// </summary>
[HttpGet("{id:guid}")]
[ProducesResponseType(typeof(UserDto), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<ActionResult<UserDto>> GetUser(Guid id, CancellationToken cancellationToken)
{
var user = await _userService.GetUserByIdAsync(id, cancellationToken);
return Ok(user);
}
/// <summary>
/// Creates a new user
/// </summary>
[HttpPost]
[ProducesResponseType(typeof(UserDto), StatusCodes.Status201Created)]
[ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]
public async Task<ActionResult<UserDto>> CreateUser(
[FromBody] CreateUserRequest request,
CancellationToken cancellationToken)
{
var user = await _userService.CreateUserAsync(request, cancellationToken);
return CreatedAtAction(nameof(GetUser), new { id = user.Id }, user);
}
/// <summary>
/// Updates an existing user
/// </summary>
[HttpPut("{id:guid}")]
[ProducesResponseType(typeof(UserDto), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<ActionResult<UserDto>> UpdateUser(
Guid id,
[FromBody] UpdateUserRequest request,
CancellationToken cancellationToken)
{
var user = await _userService.UpdateUserAsync(id, request, cancellationToken);
return Ok(user);
}
/// <summary>
/// Deletes a user
/// </summary>
[HttpDelete("{id:guid}")]
[ProducesResponseType(StatusCodes.Status204NoContent)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> DeleteUser(Guid id, CancellationToken cancellationToken)
{
await _userService.DeleteUserAsync(id, cancellationToken);
return NoContent();
}
}Why Use a Service Layer?
csharp
// Application/Interfaces/IUserService.cs
public interface IUserService
{
Task<PagedResult<UserDto>> GetUsersAsync(PaginationParams pagination, CancellationToken cancellationToken);
Task<UserDto> GetUserByIdAsync(Guid id, CancellationToken cancellationToken);
Task<UserDto> CreateUserAsync(CreateUserRequest request, CancellationToken cancellationToken);
Task<UserDto> UpdateUserAsync(Guid id, UpdateUserRequest request, CancellationToken cancellationToken);
Task DeleteUserAsync(Guid id, CancellationToken cancellationToken);
}
// Application/Services/UserService.cs
public class UserService : IUserService
{
private readonly IUserRepository _userRepository;
private readonly IMapper _mapper;
private readonly IValidator<CreateUserRequest> _createValidator;
private readonly ILogger<UserService> _logger;
public UserService(
IUserRepository userRepository,
IMapper mapper,
IValidator<CreateUserRequest> createValidator,
ILogger<UserService> logger)
{
_userRepository = userRepository;
_mapper = mapper;
_createValidator = createValidator;
_logger = logger;
}
public async Task<UserDto> GetUserByIdAsync(Guid id, CancellationToken cancellationToken)
{
var user = await _userRepository.GetByIdAsync(id, cancellationToken)
?? throw new NotFoundException($"User with ID {id} not found");
return _mapper.Map<UserDto>(user);
}
public async Task<UserDto> CreateUserAsync(CreateUserRequest request, CancellationToken cancellationToken)
{
// Validate
var validationResult = await _createValidator.ValidateAsync(request, cancellationToken);
if (!validationResult.IsValid)
{
throw new ValidationException(validationResult.Errors);
}
// Check for duplicate email
var existingUser = await _userRepository.GetByEmailAsync(request.Email, cancellationToken);
if (existingUser != null)
{
throw new ConflictException("A user with this email already exists");
}
// Create user
var user = _mapper.Map<User>(request);
user.CreatedAt = DateTime.UtcNow;
await _userRepository.AddAsync(user, cancellationToken);
await _userRepository.SaveChangesAsync(cancellationToken);
_logger.LogInformation("Created user {UserId} with email {Email}", user.Id, user.Email);
return _mapper.Map<UserDto>(user);
}
// ... other methods
}DTOs and Mapping
csharp
// Application/DTOs/UserDto.cs
public record UserDto
{
public Guid Id { get; init; }
public string Email { get; init; } = string.Empty;
public string FullName { get; init; } = string.Empty;
public string Role { get; init; } = string.Empty;
public DateTime CreatedAt { get; init; }
public DateTime? LastLoginAt { get; init; }
}
// Application/DTOs/CreateUserRequest.cs
public record CreateUserRequest
{
public string Email { get; init; } = string.Empty;
public string FirstName { get; init; } = string.Empty;
public string LastName { get; init; } = string.Empty;
public string Password { get; init; } = string.Empty;
}
// Application/DTOs/UpdateUserRequest.cs
public record UpdateUserRequest
{
public string? FirstName { get; init; }
public string? LastName { get; init; }
public string? Email { get; init; }
}
// Application/Mapping/UserProfile.cs (AutoMapper)
public class UserProfile : Profile
{
public UserProfile()
{
CreateMap<User, UserDto>()
.ForMember(d => d.FullName, opt => opt.MapFrom(s => $"{s.FirstName} {s.LastName}"));
CreateMap<CreateUserRequest, User>()
.ForMember(d => d.Id, opt => opt.MapFrom(_ => Guid.NewGuid()))
.ForMember(d => d.PasswordHash, opt => opt.Ignore());
CreateMap<UpdateUserRequest, User>()
.ForAllMembers(opt => opt.Condition((src, dest, srcMember) => srcMember != null));
}
}Validation with FluentValidation
csharp
// Application/Validators/CreateUserRequestValidator.cs
public class CreateUserRequestValidator : AbstractValidator<CreateUserRequest>
{
public CreateUserRequestValidator()
{
RuleFor(x => x.Email)
.NotEmpty().WithMessage("Email is required")
.EmailAddress().WithMessage("Invalid email format")
.MaximumLength(255).WithMessage("Email must not exceed 255 characters");
RuleFor(x => x.FirstName)
.NotEmpty().WithMessage("First name is required")
.MaximumLength(100).WithMessage("First name must not exceed 100 characters")
.Matches(@"^[a-zA-Z\s]+$").WithMessage("First name can only contain letters");
RuleFor(x => x.LastName)
.NotEmpty().WithMessage("Last name is required")
.MaximumLength(100).WithMessage("Last name must not exceed 100 characters");
RuleFor(x => x.Password)
.NotEmpty().WithMessage("Password is required")
.MinimumLength(8).WithMessage("Password must be at least 8 characters")
.Matches(@"[A-Z]").WithMessage("Password must contain at least one uppercase letter")
.Matches(@"[a-z]").WithMessage("Password must contain at least one lowercase letter")
.Matches(@"[0-9]").WithMessage("Password must contain at least one number")
.Matches(@"[^a-zA-Z0-9]").WithMessage("Password must contain at least one special character");
}
}
// Register validators in Program.cs
builder.Services.AddValidatorsFromAssemblyContaining<CreateUserRequestValidator>();How Do You Handle Exceptions Globally?
csharp
// Domain/Exceptions/AppException.cs
public abstract class AppException : Exception
{
public abstract int StatusCode { get; }
public virtual string Title => "An error occurred";
protected AppException(string message) : base(message) { }
}
public class NotFoundException : AppException
{
public override int StatusCode => StatusCodes.Status404NotFound;
public override string Title => "Resource not found";
public NotFoundException(string message) : base(message) { }
}
public class ConflictException : AppException
{
public override int StatusCode => StatusCodes.Status409Conflict;
public override string Title => "Conflict";
public ConflictException(string message) : base(message) { }
}
public class ForbiddenException : AppException
{
public override int StatusCode => StatusCodes.Status403Forbidden;
public override string Title => "Forbidden";
public ForbiddenException(string message) : base(message) { }
}
// API/Middleware/ExceptionHandlingMiddleware.cs
public class ExceptionHandlingMiddleware
{
private readonly RequestDelegate _next;
private readonly ILogger<ExceptionHandlingMiddleware> _logger;
public ExceptionHandlingMiddleware(RequestDelegate next, ILogger<ExceptionHandlingMiddleware> logger)
{
_next = next;
_logger = logger;
}
public async Task InvokeAsync(HttpContext context)
{
try
{
await _next(context);
}
catch (Exception ex)
{
await HandleExceptionAsync(context, ex);
}
}
private async Task HandleExceptionAsync(HttpContext context, Exception exception)
{
var (statusCode, title, detail) = exception switch
{
AppException appEx => (appEx.StatusCode, appEx.Title, appEx.Message),
ValidationException valEx => (400, "Validation Error", string.Join("; ", valEx.Errors.Select(e => e.ErrorMessage))),
_ => (500, "Internal Server Error", "An unexpected error occurred")
};
if (statusCode == 500)
{
_logger.LogError(exception, "Unhandled exception occurred");
}
else
{
_logger.LogWarning("Application exception: {Message}", exception.Message);
}
var problemDetails = new ProblemDetails
{
Status = statusCode,
Title = title,
Detail = detail,
Instance = context.Request.Path
};
context.Response.StatusCode = statusCode;
context.Response.ContentType = "application/problem+json";
await context.Response.WriteAsJsonAsync(problemDetails);
}
}Dependency Injection Setup
csharp
// Program.cs
var builder = WebApplication.CreateBuilder(args);
// Add services
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
Description = "JWT Authorization header",
Name = "Authorization",
In = ParameterLocation.Header,
Type = SecuritySchemeType.ApiKey,
Scheme = "Bearer"
});
});
// AutoMapper
builder.Services.AddAutoMapper(typeof(UserProfile).Assembly);
// FluentValidation
builder.Services.AddValidatorsFromAssemblyContaining<CreateUserRequestValidator>();
// Application services
builder.Services.AddScoped<IUserService, UserService>();
builder.Services.AddScoped<IOrderService, OrderService>();
// Infrastructure
builder.Services.AddDbContext<AppDbContext>(options =>
options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));
builder.Services.AddScoped<IUserRepository, UserRepository>();
builder.Services.AddScoped<IOrderRepository, OrderRepository>();
// Logging
builder.Services.AddLogging(logging =>
{
logging.AddConsole();
logging.AddDebug();
});
var app = builder.Build();
// Middleware pipeline
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
app.UseMiddleware<ExceptionHandlingMiddleware>();
app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();Pagination
csharp
// Application/DTOs/PaginationParams.cs
public record PaginationParams
{
private const int MaxPageSize = 100;
private int _pageSize = 10;
public int PageNumber { get; init; } = 1;
public int PageSize
{
get => _pageSize;
init => _pageSize = Math.Min(value, MaxPageSize);
}
public string? SortBy { get; init; }
public bool SortDescending { get; init; }
}
// Application/DTOs/PagedResult.cs
public record PagedResult<T>
{
public IReadOnlyList<T> Items { get; init; } = Array.Empty<T>();
public int PageNumber { get; init; }
public int PageSize { get; init; }
public int TotalCount { get; init; }
public int TotalPages => (int)Math.Ceiling(TotalCount / (double)PageSize);
public bool HasPreviousPage => PageNumber > 1;
public bool HasNextPage => PageNumber < TotalPages;
}
// Extension method for IQueryable
public static class QueryableExtensions
{
public static async Task<PagedResult<T>> ToPagedResultAsync<T>(
this IQueryable<T> query,
PaginationParams pagination,
CancellationToken cancellationToken = default)
{
var totalCount = await query.CountAsync(cancellationToken);
var items = await query
.Skip((pagination.PageNumber - 1) * pagination.PageSize)
.Take(pagination.PageSize)
.ToListAsync(cancellationToken);
return new PagedResult<T>
{
Items = items,
PageNumber = pagination.PageNumber,
PageSize = pagination.PageSize,
TotalCount = totalCount
};
}
}Caching
csharp
// Using IMemoryCache for simple caching
public class UserService : IUserService
{
private readonly IMemoryCache _cache;
private readonly IUserRepository _userRepository;
public async Task<UserDto> GetUserByIdAsync(Guid id, CancellationToken cancellationToken)
{
var cacheKey = $"user_{id}";
if (_cache.TryGetValue(cacheKey, out UserDto? cachedUser))
{
return cachedUser!;
}
var user = await _userRepository.GetByIdAsync(id, cancellationToken)
?? throw new NotFoundException($"User with ID {id} not found");
var userDto = _mapper.Map<UserDto>(user);
var cacheOptions = new MemoryCacheEntryOptions()
.SetSlidingExpiration(TimeSpan.FromMinutes(5))
.SetAbsoluteExpiration(TimeSpan.FromHours(1));
_cache.Set(cacheKey, userDto, cacheOptions);
return userDto;
}
}
// Using Response Caching
[HttpGet("{id}")]
[ResponseCache(Duration = 60, VaryByQueryKeys = new[] { "id" })]
public async Task<ActionResult<UserDto>> GetUser(Guid id) { }
// Using Output Caching (.NET 7+)
[HttpGet]
[OutputCache(Duration = 60, VaryByQueryKeys = new[] { "page", "pageSize" })]
public async Task<ActionResult<PagedResult<UserDto>>> GetUsers([FromQuery] PaginationParams pagination) { }How Should You Version Your API?
csharp
// Install: Asp.Versioning.Mvc
// Program.cs
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
options.ApiVersionReader = ApiVersionReader.Combine(
new UrlSegmentApiVersionReader(),
new HeaderApiVersionReader("X-Api-Version")
);
})
.AddApiExplorer(options =>
{
options.GroupNameFormat = "'v'VVV";
options.SubstituteApiVersionInUrl = true;
});
// Controllers/v1/UsersController.cs
[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class UsersController : ControllerBase
{
[HttpGet("{id}")]
public async Task<ActionResult<UserDtoV1>> GetUser(Guid id) { }
}
// Controllers/v2/UsersController.cs
[ApiController]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class UsersController : ControllerBase
{
[HttpGet("{id}")]
public async Task<ActionResult<UserDtoV2>> GetUser(Guid id) { }
}Logging Best Practices
csharp
// Use structured logging
_logger.LogInformation(
"User {UserId} created order {OrderId} with {ItemCount} items",
userId, orderId, itemCount);
// Log appropriate levels
_logger.LogDebug("Processing request for user {UserId}", userId); // Development only
_logger.LogInformation("Order {OrderId} completed", orderId); // Normal operations
_logger.LogWarning("Rate limit reached for IP {IpAddress}", ip); // Potential issues
_logger.LogError(ex, "Failed to process payment for order {OrderId}", orderId); // Errors
// Add correlation IDs
public class CorrelationIdMiddleware
{
public async Task InvokeAsync(HttpContext context)
{
var correlationId = context.Request.Headers["X-Correlation-ID"].FirstOrDefault()
?? Guid.NewGuid().ToString();
context.Response.Headers.Add("X-Correlation-ID", correlationId);
using (_logger.BeginScope(new Dictionary<string, object>
{
["CorrelationId"] = correlationId
}))
{
await _next(context);
}
}
}Health Checks
csharp
// Program.cs
builder.Services.AddHealthChecks()
.AddDbContextCheck<AppDbContext>("database")
.AddRedis(builder.Configuration.GetConnectionString("Redis")!, "redis")
.AddCheck<ExternalApiHealthCheck>("external-api");
app.MapHealthChecks("/health", new HealthCheckOptions
{
ResponseWriter = async (context, report) =>
{
context.Response.ContentType = "application/json";
var response = new
{
status = report.Status.ToString(),
checks = report.Entries.Select(e => new
{
name = e.Key,
status = e.Value.Status.ToString(),
duration = e.Value.Duration.TotalMilliseconds
}),
totalDuration = report.TotalDuration.TotalMilliseconds
};
await context.Response.WriteAsJsonAsync(response);
}
});
// Custom health check
public class ExternalApiHealthCheck : IHealthCheck
{
private readonly HttpClient _httpClient;
public async Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context,
CancellationToken cancellationToken = default)
{
try
{
var response = await _httpClient.GetAsync("/health", cancellationToken);
return response.IsSuccessStatusCode
? HealthCheckResult.Healthy("External API is reachable")
: HealthCheckResult.Degraded("External API returned non-success status");
}
catch (Exception ex)
{
return HealthCheckResult.Unhealthy("External API is unreachable", ex);
}
}
}Rate Limiting
csharp
// .NET 7+ built-in rate limiting
builder.Services.AddRateLimiter(options =>
{
options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
options.AddFixedWindowLimiter("fixed", config =>
{
config.Window = TimeSpan.FromMinutes(1);
config.PermitLimit = 100;
config.QueueLimit = 0;
});
options.AddSlidingWindowLimiter("sliding", config =>
{
config.Window = TimeSpan.FromMinutes(1);
config.SegmentsPerWindow = 6;
config.PermitLimit = 100;
});
options.AddTokenBucketLimiter("token", config =>
{
config.TokenLimit = 100;
config.ReplenishmentPeriod = TimeSpan.FromSeconds(10);
config.TokensPerPeriod = 10;
});
});
app.UseRateLimiter();
// Apply to controller
[EnableRateLimiting("fixed")]
public class UsersController : ControllerBase { }
// Apply to specific endpoint
[HttpPost]
[EnableRateLimiting("token")]
public async Task<IActionResult> CreateUser() { }A well-structured API is a joy to work with. Keep controllers thin, validate early, handle errors gracefully, and always think about the developer experience for API consumers.
These patterns form the foundation of enterprise-grade ASP.NET Core APIs. Apply them consistently across your projects for maintainable, scalable, and robust web services.