C# Web API - Una mirada completa a la estructuración de API con el enfoque de Derek Comartin

Estructuras comunes de API

Derek comienza planteando la pregunta que la mayoría de los desarrolladores se hacen al crear un nuevo proyecto de API web en Visual Studio:

"¿Cómo debe estructurar su API HTTP?"

Inmediatamente reconoce que los proyectos de API web pueden organizarse de muchas maneras. Entre las estructuras de carpetas más comunes que ve Derek:

• Agrupación por temas técnicos: los modelos en una carpeta Models, los controladores en una carpeta Controllers y los servicios en Services.

• Utilización de una arquitectura limpia o arquitectura en cebolla, en la que los proyectos se dividen por capas (API, aplicación, dominio, infraestructura) para orientar las dependencias.

• Combinación del diseño orientado al dominio (DDD) con la arquitectura de rebanadas verticales: agrupación de puntos finales por características, pero sin dejar de tener objetos ricos en dominios.

Derek subraya que cada uno de estos patrones puede crear una API RESTful que utilice los métodos HTTP que cabría esperar (GET, POST, PUT, DELETE) para trabajar con recursos. Pero advierte que no hay que leer demasiado solo en las estructuras de carpetas:

"Es posible que veas entidades, agregados o servicios de dominio, pero eso no significa que el código esté realizando realmente un diseño orientado a dominios, simplemente está utilizando esos patrones"

Empezando por la sencillez, no por la complejidad

Derek dice que su objetivo es sencillo:

"Una de las principales cosas que quería conseguir con esta estructura es la sencillez"

En lugar de lanzarse a una arquitectura pesada al estilo .NET Framework o replicar patrones de libros de texto, Derek opta por las API mínimas de ASP.NET Core. ¿Por qué? Porque facilitan la creación de API sin la sobrecarga de controladores y código repetitivo.

Al crear un nuevo proyecto de API web en Visual Studio o incluso en Visual Studio Code, es posible que comience con el cuadro de diálogo Nuevo proyecto y seleccione ASP.NET Core Web API. Por defecto, tendrás controladores, carpetas y mucho andamiaje. Derek argumenta que, a menudo, es mejor empezar por lo pequeño, por una estructura sencilla y limpia.

La estructura central de la API web de Derek

Derek presenta la estructura de su aplicación web utilizando .NET Core. Está diseñado para soportar servicios HTTP comunes y API RESTful que permiten la comunicación entre diferentes aplicaciones de software.

Así es como organiza su proyecto de API web:

• Archivo Endpoints - Un único archivo para ver todas las rutas disponibles en la API. En lugar de escarbar en múltiples controladores, Derek quiere un resumen rápido de cada método get, método post, solicitud put o solicitud delete que admite la API.

• Carpeta común: contiene código compartido como filtros y extensiones que se utilizan en diferentes sistemas de software.

• Carpetas de funciones - Siguiendo la filosofía de la división vertical, cada recurso nuevo o existente tiene su propia carpeta. Por ejemplo, una carpeta Posts puede incluir todo lo necesario para GET /posts/{id}, POST /posts, PUT /posts/{id} y DELETE /posts/{id}.

• Carpeta de datos: contiene el modelo de datos y las asignaciones de entidades. En este caso, Entity Framework Core podría utilizarse para una integración perfecta con bases de datos.

Al agrupar los puntos finales por función, Derek evita la dispersión de la lógica en varias carpetas no relacionadas.

Por qué no fuerza el diseño orientado al dominio

Derek ya ha utilizado el diseño basado en dominios en el pasado, pero en esta estructura de API web de C# hace una elección clave:

"No vamos a utilizar el diseño basado en dominios"

En su lugar, "deja que los datos sean datos" Sus modelos de datos son clases simples con propiedades sencillas como:

public class Post  
{  
    public int Id { get; set; }  
    public string Title { get; set; }  
}

public class Post  
{  
    public int Id { get; set; }  
    public string Title { get; set; }  
}

No deben incluirse comportamientos innecesarios. Cuando se envía una solicitud POST para crear un nuevo recurso, la API simplemente lo guarda. Cuando se envía una petición DELETE con un parámetro id, se elimina ese recurso.

Este enfoque adopta el estilo arquitectónico de Representational State Transfer (REST) tratando los puntos finales de la API como verbos (método get, método post, método put, método delete) que actúan sobre recursos como Post, User o Comment.

Viaje por la solución en Visual Studio

En este punto, Derek abre su solución Visual Studio y nos da una vuelta:

• El archivo Endpoints enumera todas las rutas, ya sea una solicitud GET para obtener datos, una solicitud POST para añadir un nuevo recurso, una solicitud PUT para actualizar datos o un método DELETE para eliminar un recurso existente.

• La carpeta Data contiene asignaciones para entidades como Post, User y Comment, conectadas a una base de datos mediante Entity Framework.

• La carpeta Common contiene lógica compartida para servicios HTTP como filtros de validación y extensiones.

• Cada carpeta de características (Posts, Comments, Authentication) tiene todo el código necesario para ese recurso.

Esta disposición limpia de las carpetas de proyectos evita el lío de tener que rebuscar en un cuadro de diálogo de proyectos demasiado complejo o en una carpeta de controladores dispersa.

Desglosando un punto final

Derek explica que cada punto final de su API web ASP.NET Core es una unidad de trabajo autónoma con tres pasos claros:

1. Mapeo - Define el método HTTP y la ruta. Por ejemplo, una solicitud de eliminación podría asignar DELETE /posts/{id} a un método de gestión.

2. Contratos de solicitud y respuesta - Cada punto final tiene su propio cuerpo de solicitud y tipo de respuesta. De este modo, los servicios HTTP resultan más claros y se evita crear capas de DTO duplicados.

3. Lógica - El método de gestión real, en el que la API obtiene información de la base de datos, actualiza un modelo de datos o devuelve un código de estado como return CreatedAtAction o return NoContent.

Dado que Derek utiliza API mínimas, estos manejadores son métodos estáticos. Con ASP.NET Core, esto significa que puede inyectar dependencias directamente, sin necesidad de una voluminosa clase de controlador.

Por qué las API mínimas son adecuadas

Derek elogia las API mínimas por su sencillez. Con la plantilla mínima de ASP.NET Core, puede iniciar un proyecto de API web con sólo unas pocas líneas en Program.cs:

var app = WebApplication.CreateBuilder(args).Build();

var app = WebApplication.CreateBuilder(args).Build();

A partir de ahí, se añaden los métodos get, los métodos post y las peticiones put de forma sencilla.

Esta simplicidad ayuda a evitar el exceso de ingeniería, algo que Derek ve con demasiada frecuencia cuando los desarrolladores copian ciegamente plantillas de paquetes nuget o fuerzan nuevas clases de controlador para cada punto final menor.

Cómo puede evolucionar la complejidad con el tiempo

Derek pone un ejemplo real: la función "Me gusta".

• Al principio, es sencillo: comprueba si existe un like y añádelo si no.

• Pero más adelante, la aplicación de software podría necesitar devolver un recuento de similares al instante para páginas web o dispositivos móviles.

• Para escalar, podría desnormalizar los datos añadiendo una propiedad LikeCount al modelo de datos Post.

Esto abre nuevos retos:

• Cada método put o delete que afecte a likes debe actualizar correctamente el recuento.

• Si alguien añade un registro similar sin llamar a la API, el recuento es incorrecto.

Derek muestra que, a medida que aumenta la complejidad, se pueden añadir patrones como:

• Patrón de repositorio para encapsular el acceso a los datos.

• Agregue raíces para manejar comportamientos (como incrementar LikeCount).

• Patrón de salida para garantizar que los eventos (como "PostLiked") se publican.

Pero su punto clave está claro:

"No empiece por aquí. Empieza por lo sencillo y evoluciona solo si es necesario"

Conclusión con la aportación de Derek

Derek termina volviendo a su lección principal para desarrolladores de API web en C#:

"Empieza por lo sencillo"

Cuando se utiliza la API web de ASP.NET Core o la API web de ASP.NET en Visual Studio, es fácil excederse en la ingeniería desde el primer día, añadiendo todas las carpetas, patrones y paquetes NuGet que se hayan visto jamás.

Pero Derek advierte: no apliques soluciones a ciegas. Comprenda los métodos HTTP que necesita, los datos con los que trabaja y los sistemas de software entre los que permite la comunicación. Construya sus API RESTful paso a paso.

Para quienes utilizan Visual Studio Code o cualquier otro entorno de desarrollo integrado, su consejo es válido: Tanto si se trata de un proyecto nuevo como de un recurso ya existente, hay que mantener la estructura del proyecto lo más simple posible, y solo añadir patrones cuando la complejidad del mundo real lo exija.

Conclusión

El vídeo de Derek Comartin es algo más que una guía para crear una API web en C#: es un recordatorio de que una buena arquitectura empieza por la claridad, no por el desorden. A través de un recorrido por su configuración real de la API web ASP.NET Core en Visual Studio, muestra cómo las API mínimas, las carpetas de funciones y los modelos de datos sencillos pueden formar la base de las API RESTful que permiten una comunicación fluida entre diferentes aplicaciones de software sin complicar en exceso el diseño.

Si quieres ver este enfoque en acción y escuchar la perspectiva de Derek de primera mano, su vídeo es un recurso excelente. Su canal está repleto de debates igualmente perspicaces sobre sistemas de software, servicios web y desarrollo de ASP.NET Core, que todo desarrollador que desee mejorar su oficio y mantener sus proyectos limpios, prácticos y orientados al futuro debe seguir.