Best Coding Practices for .NET Core API Development

Building robust, scalable, and maintainable APIs in .NET Core requires following proven coding practices. Here are 12 essential practices for creating high-quality .NET Core APIs.

1. Use Layered Architecture

Separate your code into distinct layers:

• Controllers handle requests/responses
• Services contain business logic
• Repositories handle data access

[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    private readonly IOrderService _orderService;

    public OrdersController(IOrderService orderService)
    {
        _orderService = orderService;
    }

    [HttpGet]
    public async Task<IActionResult> GetOrders()
    {
        var orders = await _orderService.GetOrdersAsync();
        return Ok(orders);
    }
}

2. Follow Naming Conventions

Use consistent naming throughout your codebase:

• PascalCase for classes and methods
• camelCase for variables and parameters
• Descriptive names that clearly indicate purpose

3. Apply Dependency Injection

Leverage .NET Core's built-in DI container:

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

4. Use Async Programming

Always use async/await for I/O operations:

public async Task<Order> CreateOrderAsync(CreateOrderRequest request)
{
    var order = await _repository.CreateAsync(request.ToEntity());
    return order;
}

5. Handle Exceptions Globally

Implement middleware for centralized exception handling:

app.UseExceptionHandler(errorApp =>
{
    errorApp.Run(async context =>
    {
        context.Response.StatusCode = 500;
        await context.Response.WriteAsync("An error occurred.");
    });
});

6. Validate Inputs

Use model validation attributes:

public class CreateOrderRequest
{
    [Required]
    [StringLength(100)]
    public string CustomerName { get; set; }

    [Required]
    [EmailAddress]
    public string Email { get; set; }
}

7. Secure Your API

Implement authentication and authorization:

• Use JWT or OAuth2
• Enforce HTTPS
• Apply rate limiting
• Validate all inputs

8. Version Your API

Use API versioning to manage changes:

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/orders")]
public class OrdersController : ControllerBase
{
    // Implementation
}

9. Write Tests

Cover your code with unit and integration tests:

[Fact]
public async Task GetOrders_ReturnsOrderList()
{
    // Arrange, Act, Assert
    var result = await _service.GetOrdersAsync();
    Assert.NotNull(result);
}

10. Implement Logging

Use structured logging for better observability:

_logger.LogInformation("Order {OrderId} created", order.Id);

11. Optimize Performance

• Use response caching
• Implement pagination
• Optimize database queries
• Use background services for heavy operations

12. Document Your API

Use Swagger for API documentation:

builder.Services.AddSwaggerGen();

Conclusion

These practices will help you build APIs that are maintainable, secure, and performant. Start implementing them incrementally in your projects for the best results.

What practices do you find most valuable in your .NET Core development?