Hey dev, en teoría, hacer una API en .NET es simple.
En la práctica, muchas terminan siendo difíciles de mantener, escalar… y hasta debuguear.

Estos son 3 errores que veo constantemente en proyectos reales y cómo evitarlos sin sobreingeniería.

Error #1: Meter lógica de negocio en los controllers

El problema es el siguiente: imagina un controller así

[HttpPost]
public async Task<IActionResult> Create(OrderRequest request)
{
    if (request.Total <= 0)
        return BadRequest("Invalid total");

    var order = new Order
    {
        Total = request.Total,
        CreatedAt = DateTime.UtcNow
    };

    await _dbContext.Orders.AddAsync(order);
    await _dbContext.SaveChangesAsync();

    return Ok(order);
}

Parece correcto y hasta simple, ¿no? Peeero....

• Estás mezclando validación, lógica y acceso a datos… ¡Fatal!
• No es reutilizable
• Es difícil de testear
• Crece rápido y se vuelve inmanejable, o sea no escala

En los dos primeros puntos de arriba, estás violando el principio SRP de responsabilidad única y DRY.

La solución sería:

• Delegar a Servicios o handlers

Tu controller quedaría así:

[HttpPost]
public async Task<IActionResult> Create(OrderRequest request)
{
    var result = await _orderService.CreateAsync(request);
    return result.ToActionResult();
}

Tu servicio quedaría así:

public async Task<Result<OrderResponse>> CreateAsync(OrderRequest request)
{
    if (request.Total <= 0)
        return Result.Fail("Invalid total");

    var order = new Order
    {
        Total = request.Total,
        CreatedAt = DateTime.UtcNow
    };

    await _repository.AddAsync(order);

    return Result.Ok(new OrderResponse(order.Id, order.Total));
}

Los beneficios reales que obtienes:

• Controller limpio y con responsabilidad única y bien definida
• Lógica reutilizable en el servicio
• Tests unitarios más desacoplados y sin ASP.NET

Error #2: No versionar el API

El problema es que tienes endpoints así:

GET /api/orders

Y si luego cambias el contrato (o sea el dto ya sea de request o response):

// antes
{ "total": 100 }

// después
{ "amount": 100, "currency": "USD" }

Boom! Estimado dev, rompiste todos tus clientes de tu API.

La solución es versionando desde el día 1

Por ejemplo, puedes versionar por URL. Esto es simple y efectivo:

GET /api/v1/orders
GET /api/v2/orders

También puedes versionar por header. Esto es aún más limpio:

GET /api/orders
version: 1

En un próximo artículo te enseñaré cómo versionar un API como se hace en la industria.

Error #3: No manejar errores correctamente

Típicamente verás este código:

try
{
    var data = await _service.GetAsync();
    return Ok(data);
}
catch (Exception ex)
{
    return StatusCode(500, ex.Message);
}

Los problemas de este código son:

• Exponer información sensible
• Tienes respuestas inconsistentes
• Es difícil de monitorear

La solución es tener un manejo centralizado y respuestas estándar.

Por ejemplo puedes implementar un middleware global

public class ExceptionMiddleware
{
    private readonly RequestDelegate _next;

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

    public async Task Invoke(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (Exception)
        {
            context.Response.StatusCode = 500;
            await context.Response.WriteAsJsonAsync(new
            {
                error = "Internal server error"
            });
        }
    }
}

También deberías estar aplicando logs estructurados. Tengo un artículo donde te enseño. Haz clic aquí.

En conclusión, estimado Dev, ya sabes, hacer una API funcional es relativamente fácil, más hoy con la IA, pero hacer una API mantenible es otra historia.

Con base en mi experiencia, habiendo trabajado en muchos proyectos, puedo decirte que sólo con corregir estos 3 errores muy comunes, ya estás por encima de la mayoría de las APIs en producción.

Si esta entrada te ha encantado, crack, compártela! 😜

Créditos de la imagen de portada: Foto de Sirisvisual en Unsplash