.NET Web API Development: The Ultimate Do's and Don'ts Guide

Building robust, maintainable, and secure Web APIs in .NET requires more than just knowing the syntax. It demands adherence to established patterns, understanding of HTTP semantics, and awareness of common pitfalls that can turn a well-intentioned API into a maintenance nightmare. This guide compiles the most critical Do's and Don'ts for modern .NET Web API development.

Part 1: Critical Do's

✅ DO Use [ApiController] for Controllers

The [ApiController] attribute enables several opinionated, helpful behaviors automatically. It enforces attribute routing, triggers automatic ProblemDetails responses for validation errors, and infers binding sources for parameters.

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    // Your actions
}

✅ DO Keep Controllers Thin

Controllers should be the "HTTP translation layer," not the business logic layer. They should be responsible for:

• Receiving requests and returning responses
• Validating input
• Mapping between DTOs and domain models
• Delegating work to services

// ✅ CORRECT - Thin controller
[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    private readonly IOrderService _orderService;
    private readonly IMapper _mapper;

    public OrdersController(IOrderService orderService, IMapper mapper)
    {
        _orderService = orderService;
        _mapper = mapper;
    }

    [HttpGet("{id}")]
    public async Task> GetOrder(int id)
    {
        var order = await _orderService.GetOrderAsync(id);
        if (order == null)
            return NotFound();

        return Ok(_mapper.Map(order));
    }
}

✅ DO Use DTOs Instead of Exposing Entities

Never expose your Entity Framework Core entities directly in your API. This couples your database schema to your API contract, causing breaking changes when your data model evolves.

// ❌ WRONG - Exposing Entity
[HttpGet]
public async Task>> GetProducts()
{
    return await _context.Products.ToListAsync();
}

// ✅ CORRECT - Using DTO
[HttpGet]
public async Task>> GetProducts()
{
    var products = await _context.Products.ToListAsync();
    return Ok(_mapper.Map>(products));
}

✅ DO Use Proper HTTP Status Codes

Use the appropriate HTTP status codes to communicate success or failure to the client. This makes your API self-documenting and easier to consume.

// ✅ CORRECT - Using proper status codes
[HttpPost]
public async Task> CreateOrder(CreateOrderRequest request)
{
    var order = await _orderService.CreateOrderAsync(request);
    return CreatedAtAction(nameof(GetOrder), new { id = order.Id }, order);
}

[HttpDelete("{id}")]
public async Task DeleteOrder(int id)
{
    var result = await _orderService.DeleteOrderAsync(id);
    if (!result) return NotFound();
    return NoContent();
}

✅ DO Use ProblemDetails for Errors

Use ProblemDetails (RFC 7807) for consistent error responses. This is the standard approach for communicating errors in ASP.NET Core.

// ✅ CORRECT - Using ProblemDetails
[ApiController]
public class ProductsController : ControllerBase
{
    [HttpGet("{id}")]
    public async Task> GetProduct(int id)
    {
        var product = await _productService.GetProductAsync(id);
        if (product == null)
        {
            return Problem(
                title: "Product not found",
                detail: $"The product with ID {id} was not found.",
                statusCode: StatusCodes.Status404NotFound,
                type: "https://example.com/problems/product-not-found"
            );
        }
        return Ok(product);
    }
}

✅ DO Use Dependency Injection

Use constructor-based dependency injection for all dependencies. This makes your code more testable, maintainable, and follows the explicit dependencies principle.

// ✅ CORRECT - DI via constructor
public class ProductsController : ControllerBase
{
    private readonly IProductService _productService;
    private readonly ILogger _logger;

    public ProductsController(IProductService productService, ILogger logger)
    {
        _productService = productService;
        _logger = logger;
    }
}

✅ DO Use Async/Await

Use asynchronous programming for I/O-bound operations. This improves scalability by freeing threads for other work while awaiting I/O completion.

// ✅ CORRECT - Async all the way
[HttpGet]
public async Task>> GetProducts()
{
    var products = await _context.Products
        .AsNoTracking()
        .ToListAsync();
    return Ok(_mapper.Map>(products));
}

Part 2: Critical Don'ts

❌ DON'T Use HttpClient Directly Without HttpClientFactory

Creating a new HttpClient for each request can lead to socket exhaustion. Always use IHttpClientFactory to manage HttpClient instances centrally.

// ❌ WRONG - Causes socket exhaustion
using var client = new HttpClient();
var response = await client.GetAsync(url);

// ✅ CORRECT - Use IHttpClientFactory
public class ProductService
{
    private readonly HttpClient _client;

    public ProductService(HttpClient client) // Injected via factory
    {
        _client = client;
    }
}

// Program.cs
builder.Services.AddHttpClient(client =>
{
    client.BaseAddress = new Uri("https://api.example.com/");
});

❌ DON'T Use Database Exceptions for Control Flow

Don't use exceptions for expected scenarios. Check for existence before updating or deleting, and return appropriate status codes.

// ❌ WRONG - Using exceptions for flow control
[HttpPut("{id}")]
public async Task UpdateProduct(int id, ProductDto product)
{
    try
    {
        var entity = await _context.Products.FindAsync(id);
        // Update logic
        await _context.SaveChangesAsync();
        return Ok();
    }
    catch (DbUpdateConcurrencyException)
    {
        return Conflict();
    }
}

// ✅ CORRECT - Check explicitly
[HttpPut("{id}")]
public async Task UpdateProduct(int id, ProductDto product)
{
    var entity = await _context.Products.FindAsync(id);
    if (entity == null)
        return NotFound();

    _mapper.Map(product, entity);
    await _context.SaveChangesAsync();
    return Ok();
}

❌ DON'T Use Magic Strings

Avoid hardcoding strings for session keys, cookie names, policy names, or error messages. Define them in constants or configuration.

// ❌ WRONG - Magic strings
if (HttpContext.User.Identity.Name == "admin") { }

// ✅ CORRECT - Constants
public static class ClaimTypes
{
    public const string Admin = "admin";
}

if (HttpContext.User.IsInRole(ClaimTypes.Admin)) { }

❌ DON'T Use Console.WriteLine or Debug.Write

Use structured logging with a library like Serilog. This enables proper log levels, sinks, and structured data.

// ❌ WRONG
Console.WriteLine($"Order {orderId} created");

// ✅ CORRECT
_logger.LogInformation("Order {OrderId} created by {UserId}", orderId, userId);

❌ DON'T Return Plain Strings for Errors

Always return structured error responses (ProblemDetails or ValidationProblemDetails) instead of plain strings.

// ❌ WRONG - Plain string error
return BadRequest("Order lines cannot be empty");

// ✅ CORRECT - ProblemDetails
return Problem(
    title: "Validation Failed",
    detail: "Order lines cannot be empty.",
    statusCode: StatusCodes.Status400BadRequest
);

❌ DON'T Ignore Versioning

Always version your APIs to handle breaking changes without breaking clients.

// ✅ CORRECT - API Versioning
[ApiController]
[Route("api/v{version:apiVersion}/orders")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class OrdersController : ControllerBase
{
    [MapToApiVersion("1.0")]
    [HttpGet("{id}")]
    public async Task> GetOrderV1(int id)
    {
        // Returns old format
    }

    [MapToApiVersion("2.0")]
    [HttpGet("{id}")]
    public async Task> GetOrderV2(int id)
    {
        // Returns new format with additional fields
    }
}

❌ DON'T Hardcode Configuration

Store configuration in appsettings.json and use the Options pattern. This makes your app environment-aware and more secure.

// ❌ WRONG - Hardcoded
var connectionString = "Server=localhost;Database=MyDb;";

// ✅ CORRECT - Options pattern
public class DatabaseOptions
{
    public string ConnectionString { get; set; } = string.Empty;
}

// Program.cs
builder.Services.Configure(
    builder.Configuration.GetSection("Database"));

// Usage
private readonly DatabaseOptions _dbOptions;
public MyService(IOptions options)
{
    _dbOptions = options.Value;
}

Part 3: Best Practices Summary

Common Pitfalls Summary

Choosing the Right Style

In .NET, you can choose between Controllers and Minimal APIs:

The Bottom Line