Hey dev, antes que nada espero que estés bien tu y los tuyos 🐿️✌🏼 En esta ocasión te voy a conversar de los tipos que un método dentro un controlador, es decir un endpoint debe retornar al cliente, si bien hay muchas opciones, de todas, resaltan 3 y aquí te las presentaré, como ya sabes, siempre con un lenguaje sencillo, al grano, y con ejemplos reales, con calidad de producción, no sólo teórico. Vamos!

Entendiendo el contexto...

Cuando estamos construyendo una API REST en .NET, es esencial tener claridad sobre los tipos de respuestas que nuestros endpoints deberían devolver. Elegir el tipo adecuado de respuesta no solo impacta la funcionalidad, sino también la legibilidad, mantenimiento y rendimiento de la aplicación.

A continuación te presento los tipos más comunes que puedes retornar desde tus endpoints en .NET: IActionResult, ActionResult<T> y FileResult (junto con sus variantes).

Si quieres la documentación oficial donde se definen detalles de estos tipos aquí la puedes encontrar.

IActionResult

En .NET IActionResult es la interfaz que todos los tipos de resultados de acción implementan. Es el tipo más general y flexible que puedes usar para retornar diferentes tipos de respuestas HTTP desde un endpoint de tu API.

Características y cuándo usarlo

• Flexible: Permite retornar cualquier tipo de respuesta HTTP, desde una respuesta con un cuerpo de datos (como un objeto o JSON) hasta una respuesta con solo un código de estado (como un 404 Not Found o un 200 OK).
• Versátil: Usar IActionResult permite que tu endpoint retorne tanto un tipo de dato específico como un código de estado HTTP, sin necesidad de especificar el tipo exacto de respuesta que devolverás.

Ejemplo:

        [HttpGet("title")]
        public async Task<IActionResult> Get(string? title, [FromQuery] PaginationDto pagination)
        {
            var response = await service.GetAsync(title, pagination);
            return response.Success ? Ok(response) : BadRequest(response);
        }

ActionResult<T>

ActionResult<T> es una variante de IActionResult que se utiliza cuando quieres retornar un tipo específico (como un modelo, un DTO o un response homogéneo genérico para todo el API) junto con el código de estado HTTP adecuado.

Este tipo es más estricto que IActionResult, ya que especificas explícitamente el tipo de objeto que vas a devolver, lo que puede ayudar a mejorar la claridad y la seguridad del código.

En sistemas modernos de producción, ActionResult<T> es más común debido a la claridad y soporte para herramientas como Swagger, pero no hay problema en usar IActionResult si se ajusta mejor a tu caso.

Cuándo usarlo:

• Tipado explícito: Retorna un tipo específico de datos, lo que ayuda a garantizar que los datos devueltos sean del tipo esperado (por ejemplo, un objeto de un modelo concreto).
• Manejo de códigos HTTP: Aunque está más tipado, aún puedes devolver diferentes códigos de estado HTTP utilizando métodos como Ok(), NotFound(), BadRequest(), etc.

Ejemplo:

        [HttpGet("title")]
        public async Task<ActionResult<ICollection<ConcertResponseDto>>> Get(string? title, [FromQuery]PaginationDto pagination)
        {
            var response = await service.GetAsync(title, pagination);//response retorna una lista
            return response.Success ? Ok(response) : BadRequest(response);
        }

Y si estás usando un enfoque de respuestas homogéneas (Standard API Responses) como te lo explico en este artículo el método podría quedar más verboso, aunque en ciertas ocasiones por legibilidad sea necesario, así:

        [HttpGet("title")]
        public async Task<ActionResult<BaseResponseGeneric<ICollection<ConcertResponseDto>>>> Get(string? title, [FromQuery]PaginationDto pagination)
        {
            var response = await service.GetAsync(title, pagination); //response viene "envuelto" en una clase llamada BaseResponseGeneric
            return response.Success ? Ok(response) : BadRequest(response);
        }

FileResult y sus derivados

En algunos casos, un endpoint de tu API REST puede necesitar devolver archivos, como imágenes, documentos, o cualquier otro tipo de archivo binario.

FileResult es el tipo más adecuado para manejar estos casos.

FileResult es un tipo base de la respuesta, y existen variantes como PhysicalFileResult, FileStreamResult, o VirtualFileResult que te permiten trabajar con archivos locales, flujos de archivos o archivos en rutas virtuales respectivamente.

Características y cuándo usarlo

• Manejo de archivos: Específicamente diseñado para retornar archivos desde el servidor al cliente.
• Encabezados HTTP adecuados: FileResult se encarga de agregar los encabezados correctos para la descarga del archivo, como el tipo MIME (por ejemplo, application/pdf o image/png).

Ejemplo:

[HttpGet("descargar-archivo/{archivoNombre}")]
public async Task<FileResult> DescargarArchivoAsync(string archivoNombre)
{
    var path = Path.Combine("ruta/del/archivo", archivoNombre);

    if (!System.IO.File.Exists(path))
        return null;  //Si el archivo no existe, retorna null o NotFound

    var fileStream = new FileStream(path, FileMode.Open, FileAccess.Read);
    
    var memoryStream = new MemoryStream();
    await fileStream.CopyToAsync(memoryStream);
    memoryStream.Position = 0;  // Asegura que el flujo de memoria comience desde el inicio
    
    return new FileContentResult(memoryStream.ToArray(), "application/pdf")
    {
        FileDownloadName = archivoNombre
    };
}

¿Cuándo utilizar cada uno de estos tipos?

IActionResult:

Usa IActionResult cuando no necesitas especificar un tipo de respuesta concreto o cuando tu endpoint debe manejar una variedad de posibles respuestas (como errores, redirecciones o resultados no tipados).

ActionResult<T>:

Usa ActionResult<T> cuando quieras devolver un objeto tipado junto con el código de estado HTTP. Esto es útil cuando el tipo de respuesta es claro y conocido (como un DTO o un modelo).

FileResult:

Usa FileResult (o sus variantes) cuando tu API necesita devolver archivos. Este tipo de respuesta maneja correctamente la descarga de archivos, estableciendo los encabezados adecuados y permitiendo que el cliente reciba el archivo sin complicaciones.

Ventajas y desventajas de cada tipo

Hey dev, no todo es color de rosa, aquí te muestro en una tablita las ventajas y desventajas de cada tipo, aunque cabe resaltar que IActionResult y ActionResult<T> son dos alternativas equiparables. FileResult toca usarlo cuando trabajas con archivos y no queda otra. Los 3 tipos son buenas prácticas y ampliamente utilizados en sistemas reales en producción.

Mejores prácticas para diseñar respuestas de API

Después de todo lo discutido entonces puedo mencionarte los siguientes 5 puntos como las best practices para que las tengas en cuenta:

1. Usa ActionResult<T> cuando sea posible: Es más explícito y mejora la mantenibilidad de tu código, ya que garantiza que las respuestas son consistentes y tipo-seguras.
2. Utiliza IActionResult para mayor flexibilidad: Si tu endpoint puede retornar múltiples tipos de respuestas o si el tipo de datos no es relevante, IActionResult es adecuado.
3. Evita sobrecargar con tipos específicos innecesarios: Si no necesitas retornar archivos o redirecciones, no es necesario usar tipos como FileResult o RedirectResult a menos que sean estrictamente necesarios.
4. Asegúrate de manejar los códigos de estado HTTP adecuadamente: No olvides devolver los códigos correctos como 200 OK, 400 Bad Request, o 404 Not Found dependiendo de la situación, para una comunicación más clara con el cliente.
5. Mantén la coherencia: Establecer un patrón coherente en tu API facilitará el mantenimiento y la comprensión del código por parte de otros desarrolladores.

Conclusión

En resumen estimado dev, al diseñar los endpoints de tu API REST en .NET, es crucial elegir el tipo de respuesta adecuado para cada caso.

ActionResult<T> y IActionResult son las opciones más recomendadas por su flexibilidad y simplicidad, mientras que FileResult es ideal para cuando necesitas manejar archivos en tus respuestas. Al seguir estas mejores prácticas, tu API será más fácil de mantener, escalar y entender 🐿️.

Si esta entrada te encantó dev, compártela no seas malito 🤣🥳✌🏼

Créditos de la imagen de portada: Foto de Volkan Olmez en Unsplash