Controladores y APIs REST en ASP.NET Core

Controladores en ASP.NET Core

Mientras que las Minimal APIs son ideales para APIs simples, los controladores ofrecen mejor organización para APIs grandes:

• Agrupación lógica de endpoints en una clase
• Herencia para compartir comportamiento
• Filtros a nivel de controlador o acción
• Mejor integración con herramientas de testing

// Estructura mínima de un controlador
[ApiController]
[Route("api/[controller]")]
public class PedidosController : ControllerBase
{
    [HttpGet]
    public IActionResult ObtenerTodos() => Ok(new[] { "pedido1", "pedido2" });
}

[ApiController] y sus comportamientos

El atributo [ApiController] activa automáticamente:

1. Validación del ModelState — devuelve 400 si los datos no son válidos
2. Inferencia de fuentes — [FromBody], [FromRoute], [FromQuery] se infieren
3. Respuestas de error estándar ProblemDetails (RFC 7807)

// Sin [ApiController] — necesitas verificar manualmente
[HttpPost]
public IActionResult Crear(ProductoDto dto)
{
    if (!ModelState.IsValid) return BadRequest(ModelState);
    // ...
}

// Con [ApiController] — validación automática, sin boilerplate
[HttpPost]
public IActionResult Crear(ProductoDto dto)
{
    // Si dto no es válido, este código nunca se ejecuta
    // ASP.NET ya devolvió un 400 con los errores
    return Ok();
}

Routing

ASP.NET Core soporta varios patrones de routing:

// Route en el controlador
[Route("api/v1/[controller]")] // [controller] → nombre del controlador sin "Controller"

// Route en el controlador con versión
[Route("api/v{version:apiVersion}/productos")]

// Routes en acciones
[HttpGet]                          // GET /api/v1/productos
[HttpGet("{id:int}")]              // GET /api/v1/productos/5
[HttpGet("{id:int}/detalle")]      // GET /api/v1/productos/5/detalle
[HttpGet("buscar/{termino}")]      // GET /api/v1/productos/buscar/laptop
[HttpGet("~/admin/productos")]     // ~ anula la ruta del controlador

// Constraints de ruta
// :int, :long, :bool, :datetime, :guid, :minlength(3), :maxlength(50), :range(1,100)
[HttpGet("{id:int:min(1)}")]       // solo enteros >= 1
[HttpGet("{slug:minlength(3)}")]   // solo strings con al menos 3 chars

Model Binding

Cómo ASP.NET extrae datos del request:

[HttpGet("{id:int}")]
public IActionResult Get(
    int id,                             // [FromRoute] inferido
    [FromQuery] string? filtro,         // ?filtro=valor
    [FromHeader(Name="X-API-Key")] string? apiKey,  // header
    [FromServices] ILogger<ProductosController> log // DI directa
)

[HttpPost]
public IActionResult Post(
    [FromBody] CrearProductoDto dto     // JSON body
)

// Form data (para uploads)
[HttpPost("upload")]
public IActionResult Upload(
    IFormFile archivo,                  // archivo multipart
    [FromForm] string descripcion       // campo de formulario
)

DataAnnotations para validación

public class PedidoRequest
{
    [Required]
    [StringLength(100)]
    public string NombreCliente { get; set; } = string.Empty;

    [EmailAddress]
    public string Email { get; set; } = string.Empty;

    [Phone]
    public string? Telefono { get; set; }

    [MinLength(1, ErrorMessage = "El pedido debe tener al menos un item")]
    public List<ItemPedidoDto> Items { get; set; } = new();

    [Range(typeof(DateTime), "2020-01-01", "2030-12-31")]
    public DateTime FechaEntrega { get; set; }

    [CreditCard]
    public string? NumeroTarjeta { get; set; }

    [Url]
    public string? SitioWeb { get; set; }

    [Compare(nameof(Email))]
    public string? ConfirmarEmail { get; set; }
}

Validación personalizada

// Atributo de validación personalizado
public class FechaFuturaAttribute : ValidationAttribute
{
    protected override ValidationResult? IsValid(object? value, ValidationContext ctx)
    {
        if (value is DateTime fecha && fecha <= DateTime.Today)
            return new ValidationResult("La fecha debe ser futura");
        return ValidationResult.Success;
    }
}

public class CambioEstadoRequest
{
    [Required]
    [FechaFutura]
    public DateTime FechaEfectiva { get; set; }

    [Required]
    public string NuevoEstado { get; set; } = string.Empty;
}

ActionResult\

El tipo de retorno recomendado para acciones que devuelven datos:

// ActionResult<T> permite devolver el tipo T o un ActionResult
[HttpGet("{id:int}")]
public async Task<ActionResult<ProductoDto>> ObtenerPorId(int id)
{
    var producto = await _service.ObtenerAsync(id);

    if (producto is null)
        return NotFound(new ProblemDetails
        {
            Title    = "Producto no encontrado",
            Detail   = $"No existe un producto con ID {id}",
            Status   = 404,
            Instance = $"/api/v1/productos/{id}"
        });

    return Ok(producto); // ActionResult envuelve el DTO
}

// Helpers de ControllerBase disponibles
// Ok(obj)             → 200 OK con body
// Created(uri, obj)   → 201 Created con Location header
// CreatedAtAction(...)→ 201 Created con URL generada
// BadRequest(obj)     → 400 Bad Request
// Unauthorized()      → 401 Unauthorized
// Forbid()            → 403 Forbidden
// NotFound()          → 404 Not Found
// NoContent()         → 204 No Content
// Conflict(obj)       → 409 Conflict

Filtros de acción

Los filtros ejecutan código antes/después de las acciones:

// Filtro personalizado
public class LogActionFilter : IActionFilter
{
    private readonly ILogger<LogActionFilter> _logger;
    private Stopwatch? _sw;

    public LogActionFilter(ILogger<LogActionFilter> logger) => _logger = logger;

    public void OnActionExecuting(ActionExecutingContext context)
    {
        _sw = Stopwatch.StartNew();
        _logger.LogInformation(
            "Ejecutando {Action}", context.ActionDescriptor.DisplayName);
    }

    public void OnActionExecuted(ActionExecutedContext context)
    {
        _sw?.Stop();
        _logger.LogInformation(
            "Completado en {Ms}ms", _sw?.ElapsedMilliseconds);
    }
}

// Registrar globalmente
builder.Services.AddControllers(opts =>
{
    opts.Filters.Add<LogActionFilter>();
});

Práctica

1. CRUD completo: Crea un ClientesController con todos los endpoints REST para Cliente(int Id, string Nombre, string Email). Incluye validación con DataAnnotations.
2. Paginación: Implementa un endpoint GET /api/clientes?pagina=1&tamaño=5 que devuelva PagedResult<ClienteDto>.
3. Validación personalizada: Crea un atributo [SoloLetras] que valide que un string solo contenga letras y úsalo en el campo Nombre de CrearClienteRequest.

En la siguiente lección aprenderemos Entity Framework Core para persistir los datos de nuestra API en una base de datos relacional.