Estructura del proyecto web API en .NET 10

Comienza con una base sólida en .NET 10 para crear una web API clara, segura y mantenible. Aquí entenderás cómo se organiza el proyecto, qué papel cumple appsettings por ambiente, cómo funciona Program.cs con el patrón builder y cuándo conviene usar controllers o la plantilla Minimal API. Todo con ejemplos directos y listos para probar.

¿Qué contiene el proyecto base en .NET 10 web API?

La plantilla inicial de .NET 10 incluye archivos y servicios clave para arrancar rápido. Identificar su propósito evita errores y acelera la configuración.

¿Para qué sirve el archivo de proyecto y el SDK?

• Define el SDK de .NET usado por la solución.
• Configura versión y opciones de C#.
• Incluye el paquete de OpenAPI para documentar la API.

¿Cómo configurar appsettings por ambiente?

• appsettings.json concentra variables como cadenas de conexión y claves para JSON Web Token.
• Permite entradas para servicios externos: conexión a WS, integración con Azure, entre otros.
• Soporta archivos por ambiente: appsettings.Development.json, y puedes crear Testing o Production según necesites.

Ejemplo mínimo de configuración:

{
  "ConnectionStrings": { "Default": "<cadena>" },
  "Jwt": { "Key": "<clave>" },
  "ExternalServices": {
    "WsUrl": "<url>",
    "Azure": { "KeyVault": "<recurso>" }
  }
}

¿Qué es el archivo http para pruebas de endpoints?

• Es un archivo de solicitudes HTTP incluido en la plantilla.
• Permite probar endpoints sin herramientas externas.

Ejemplo simple de prueba:

GET https://localhost:5001/weatherforecast

¿Cómo se orquesta con Program.cs y el patrón builder?

Program.cs encadena configuraciones y arranque de la API con un flujo claro: registrar servicios, construir la aplicación y ejecutar.

¿Cómo opera el patrón builder y el run?

• Se crea un builder que agrega servicios paso a paso.
• Se construye la app con Build y se ejecuta con Run.
• Ventaja: configuración fluida, legible y extensible.

Ejemplo orientativo:

var builder = WebApplication.CreateBuilder(args);

// Servicios de la API.
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer(); // Soporte para OpenAPI.
builder.Services.AddSwaggerGen();

var app = builder.Build();

// OpenAPI solo en desarrollo.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

// Aquí puedes mapear controllers o endpoints mínimos.
app.Run();

¿Cómo aplica MVC sin vista en APIs?

• El patrón MVC separa responsabilidades: modelo, vista y controlador.
• En una API no hay interfaz gráfica: se mantiene controller y model.
• Las URLs activan controladores y acciones; la respuesta suele ser JSON, aunque puede ser XML o archivos.

¿Cuándo usar controllers vs Minimal API y cómo mapear endpoints?

Elegir la plantilla adecuada depende del alcance y la complejidad. Entender ambos enfoques te ahorra tiempo y recursos.

¿Qué hacen los controllers con [ApiController] y [Route]?

• [ApiController] indica que la clase expone acciones de API.
• [Route] define la ruta base del controlador.
• Se organizan acciones como GET, POST o DELETE en métodos claros.

Ejemplo orientativo de controller:

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    [HttpGet]
    public IEnumerable<object> Get()
    {
        // Datos de prueba y respuesta simulada.
        var datos = new[] { "Soleado", "Nublado", "Lluvioso" };
        var rng = new Random();
        return Enumerable.Range(1, 5).Select(_ => new
        {
            Fecha = DateTime.UtcNow.AddDays(rng.Next(1, 7)),
            Estado = datos[rng.Next(datos.Length)]
        });
    }
}

¿Cómo mapear rutas en Minimal API con map get, post y delete?

• No hay carpeta Controllers: todo se define en Program.cs.
• Mapea rutas con MapGet, MapPost y MapDelete.
• Menos código y mejor rendimiento en APIs simples.

Ejemplo de Minimal API con rutas:

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

// GET simple.
app.MapGet("/weatherforecast", () =>
{
    var datos = new[] { "Soleado", "Nublado", "Lluvioso" };
    var rng = new Random();
    return Enumerable.Range(1, 3).Select(_ => new
    {
        Fecha = DateTime.UtcNow.AddDays(rng.Next(1, 5)),
        Estado = datos[rng.Next(datos.Length)]
    });
});

// Reto sugerido: devolver la hora del servidor.
app.MapGet("/hora", () => DateTime.UtcNow);

// Otras acciones típicas.
app.MapPost("/recurso", () => Results.Created("/recurso/1", new { ok = true }));
app.MapDelete("/recurso/{id}", (int id) => Results.NoContent());

app.Run();

¿En qué escenarios conviene Minimal API y rendimiento?

• Proyectos pequeños, demos o responsabilidades muy específicas.
• Casos de solo lectura o sin operaciones complejas: ejemplo, una API pública que solo devuelve datos como departamentos, mapas o días festivos.
• Beneficio clave: mejor rendimiento al reducir estructura y sobrecarga de controllers.

¿Qué parte te gustaría profundizar: configuración por ambientes, controllers o Minimal API? Comparte tus dudas o tu ejemplo de endpoint con la hora del servidor.