Rutas en APIs .NET con parámetros

Domina el manejo de rutas en APIs .NET con un enfoque práctico: desde configurar la ruta base con el atributo Route hasta crear endpoints con parámetros y devolver respuestas HTTP correctas usando ActionResult. Verás cómo evitar errores comunes, aprovechar Hot Reload y explorar endpoints con Endpoints Explorer, manteniendo un estilo REST claro y predecible.

¿Cómo configurar la ruta base en .NET?

Configurar la ruta base define cómo se accede a tu controller. Usar [Route("api/[controller]")] iguala el nombre de la ruta al nombre del controller, un patrón común para agrupar recursos de la API.

• Usa [ApiController] y ControllerBase para respuestas HTTP listas para usar.
• Prefija con api/ para separar endpoints de salud o documentación de la API pública.
• Valida con Hot Reload para aplicar cambios sin reiniciar.
• Si la URL no existe, el framework responde 404 Not Found acorde a REST.

Ejemplo base con lista precargada y GET general:

[ApiController]
[Route("api/[controller]")]
public class WeatherForecastController : ControllerBase
{
    private static List<WeatherForecast> _items;

    public WeatherForecastController()
    {
        if (_items == null)
        {
            // Inicializa 5 elementos aleatorios como en la plantilla por defecto.
            _items = Enumerable.Range(1, 5)
                .Select(i => new WeatherForecast { /* ... */ })
                .ToList();
        }
    }

    [HttpGet]
    public IEnumerable<WeatherForecast> Get() => _items;
}

¿Cómo crear endpoints con parámetros y rutas relativas o absolutas?

Definir la ruta de un endpoint con parámetro es directo. La clave está en si la ruta es relativa (se suma a la base) o absoluta (reemplaza la base).

• Relativa: sin slash inicial. Se concatena a la base del controller.
• Absoluta: con slash inicial. Ignora la ruta base y crea una nueva.
• El nombre del parámetro en la ruta debe coincidir con el del método.

Relativa (se combina con api/weatherforecast):

[HttpGet("{id}")]
public ActionResult<WeatherForecast> GetById(int id)
{
    // Validación se muestra abajo.
    return Ok(_items[id]);
}

Absoluta (no usa la base del controller):

[HttpGet("/id")] // o [Route("/id")]
public WeatherForecast GetByAbsolute(int id) => _items[id];

Apóyate en Endpoints Explorer para ver la lista de endpoints y generar un request de prueba rápidamente.

¿Cómo devolver códigos HTTP correctos con ActionResult?

Devolver el código correcto mejora la claridad del contrato REST. Un acceso fuera de rango produce una excepción y termina en 500 Internal Server Error si no lo controlas. En su lugar, valida y devuelve 400 Bad Request; en casos válidos, 200 OK.

• Usa ActionResult<T> para retornar tanto datos como estados HTTP.
• Métodos útiles: BadRequest() y Ok() ya disponibles por ControllerBase.
• Valida límites: el índice no debe ser negativo ni superar el tamaño de la lista.

Ejemplo con validación y respuestas adecuadas:

[HttpGet("{id}")]
public ActionResult<WeatherForecast> GetById(int id)
{
    if (id < 0 || id >= _items.Count)
    {
        return BadRequest(); // Request inválido: índice fuera de rango.
    }

    return Ok(_items[id]); // 200 OK con el elemento solicitado.
}

Prácticas útiles para probar:

• Usa el archivo HTTP del proyecto para lanzar requests rápidos.
• Verifica cambios con Hot Reload antes de probar.
• Prueba también con Postman para ganar experiencia en ambas herramientas.
• Completa el CRUD: crea con POST, actualiza con PUT y elimina con DELETE.

¿Quieres que revisemos tu ruta actual o un caso particular de validación? Cuéntalo en los comentarios y te ayudo a pulirlo.